Zsh Mailing List Archive
Messages sorted by:
Re: [PATCH] Document _canonical_paths.
- X-seq: zsh-workers 39063
- From: Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx>
- To: zsh-workers@xxxxxxx
- Subject: Re: [PATCH] Document _canonical_paths.
- Date: Thu, 18 Aug 2016 18:09:28 -0700
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=brasslantern-com.20150623.gappssmtp.com; s=20150623; h=from:message-id:date:in-reply-to:comments:references:to:subject :mime-version; bh=Y3MFhc+rsNm4LjMUzpiP5LbfWVasOHdzjSgbvGoTKfI=; b=iVdCuKpS8s4LP6GU4YFt2r/MVdGYfTQovIdsJypChdNTydCtBLPyUX37nTJk0lqmPT KGFI3T2iEs2JkqCUQwNQPihgIMA+wG97Dj6e96kZwX0R242QzSTtGA1SbXPIbdx8xG+9 sSMNCg/RR63GST28TILelXBY+QN8LKr7hxT20QpTTR6/un8EVHxZE+4/TQ26G34BmQfK TwC/egtTzMjl97uBSM3WjJZ6L0T68OGEitV1oHKjjbuXBNWpjywSxH+pi7mx/Nx2rNRm s9dIQ3BZ8RlFS70g6poQVZsxAg8splNfUvtRnin+m8efmbkETdbANh0uXs1kmiJl4m/9 2+pQ==
- In-reply-to: <20160818165523.GA25890@tarsus.local2>
- List-help: <mailto:email@example.com>
- List-id: Zsh Workers List <zsh-workers.zsh.org>
- List-post: <mailto:firstname.lastname@example.org>
- Mailing-list: contact zsh-workers-help@xxxxxxx; run by ezmlm
- References: <email@example.com> <160816232827.ZM19685@torch.brasslantern.com> <20160817163140.GA9003@tarsus.local2> <160817095330.ZM21532@torch.brasslantern.com> <20160818165523.GA25890@tarsus.local2>
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.
Messages sorted by: