Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: X-Qmail-Scanner-Diagnostics: from hermes.apache.org by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.99.2/21882. spamassassin: 3.4.1. Clear:RC:0(140.211.11.3):SA:0(-0.5/5.0):. Processed in 0.174181 secs); 18 Aug 2016 16:55:50 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.1 (2015-04-28) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, RP_MATCHES_RCVD autolearn=unavailable autolearn_force=no version=3.4.1 X-Envelope-From: danielsh@apache.org X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: none (ns1.primenet.com.au: domain at apache.org does not designate permitted sender hosts) Date: Thu, 18 Aug 2016 16:55:23 +0000 From: Daniel Shahaf To: zsh-workers@zsh.org Subject: Re: [PATCH] Document _canonical_paths. Message-ID: <20160818165523.GA25890@tarsus.local2> References: <1471387721-5256-1-git-send-email-danielsh@tarsus.local2> <160816232827.ZM19685@torch.brasslantern.com> <20160817163140.GA9003@tarsus.local2> <160817095330.ZM21532@torch.brasslantern.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline In-Reply-To: <160817095330.ZM21532@torch.brasslantern.com> User-Agent: Mutt/1.5.23 (2014-03-12) X-Seq: zsh-workers 39060 Bart Schaefer wrote on Wed, Aug 17, 2016 at 09:53:30 -0700: > On Aug 17, 4:31pm, Daniel Shahaf wrote: > } > } > I don't understand why you want to remove comments from the function files. > } > } To avoid duplication. > > I think of function files as source code. You wouldn't remove comments > from the C source code just because there's a manual page, would you? I draw a distinction between docstrings that describe the API contract of a function and comments that document portions of the implementation. I wouldn't remove comments. However, I would remove one of two duplicate copies of a docstring. (I'd keep the copy that's in the manual's source — in our case, yodl — and drop the other one.) > Also manual pages are installed separately in many cases (even the zsh > tarballs are split to separate the docs) and therefore sometimes the > doc isn't installed at all on a given machine. It's not duplication > when one of the copies doesn't exist ... This argument cuts both ways: somebody might choose to install the man pages and only a zcompile'd version of the autoloadable function. If we really want the docstring to be present in both locations, I think one of them should be autogenerated from the other. In the meantime, I've gone ahead and pushed the yodl part of the patch. Cheers, Daniel