Re: [PATCH] Document _canonical_paths.

[Daniel Shahaf <d.s@daniel.shahaf.name>]

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