Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm
Precedence: bulk
Received-SPF: none (ns1.primenet.com.au: domain at brasslantern.com does not designate permitted sender hosts)
From: Bart Schaefer <schaefer@brasslantern.com>
Message-Id: <160818180928.ZM30000@torch.brasslantern.com>
Date: Thu, 18 Aug 2016 18:09:28 -0700
In-Reply-To: <20160818165523.GA25890@tarsus.local2>
Comments: In reply to Daniel Shahaf <d.s@daniel.shahaf.name>
        "Re: [PATCH] Document _canonical_paths." (Aug 18,  4:55pm)
References: <1471387721-5256-1-git-send-email-danielsh@tarsus.local2> 
	<160816232827.ZM19685@torch.brasslantern.com> 
	<20160817163140.GA9003@tarsus.local2> 
	<160817095330.ZM21532@torch.brasslantern.com> 
	<20160818165523.GA25890@tarsus.local2>
To: zsh-workers@zsh.org
Subject: Re: [PATCH] Document _canonical_paths.
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii

On Aug 18,  4:55pm, Daniel Shahaf wrote:
}
} If we really want the docstring to be present in both locations, I think
} one of them should be autogenerated from the other.

I think that would be an overengineered solution to what ought to be a
non-problem.  We definitely don't want the function files being modified
by the doc formatter, and the alternative -- requiring every function
file to contain a specially-formatted comment -- is both a barrier to
users who want to contribute functions, and likely to make any such
comments more difficult to read as simple text.

If the programmer of the function went to the trouble of including a
documentary comment, it's not the job of the documentation writer to
nullify that.  If you prefer not to contribute functions that have
such comments and to write yodl instead, good for you; and if you want
to write yodl for functions that others have contributed, then that's
even better; but I object to the removal of another programmer's
commentary unless a corresponding *programming* change has made it
inaccurate or obsolete.