jerry gay wrote:
i'd rather see FUNCDOC stay. it allows us to specify just the parts of
the documentation that we need to, and generates the rest from the
source. this allows us to skip
=item void myfunc(does_not, match, source)
because it's generated from the source, so is always up to date.
i believe source should be the canonical reference, and documentation
should follow the Don't Repeat Yourself principle. if there's a way we
can make this work with a method other than FUNCDOC, i'm all ears.
[Noting IRC discussion so all get the benefit:]
We expect to have the ability to pull in function signatures in Perl 6
Pod. So, we standardize on Pod now, and update to Perl 6 Pod later, in
the expectation that we'll have a port of Pod::Simple written in PGE/TGE.
The biggest motivating factor for the change at the moment is having one
consistent format for documentation in the repository, and one
consistent way of generating human readable html or manpages.
by the way, why do you consider it deprecated? i haven't heard or read
any discussion, so i'm curious as to it's deficiencies.
It's been proposed several times, and I've pretty much agreed every
time. Last we left it was 'deprecated but give the list a chance to
comment'. So, this is the time to comment.
Allison
