Moritz Lenz:
> =begin pod
>
> =head3 C<method from_string(Str $s);>
> [..]
> =end pod
>
> method from_string(Str $s){
> # implementation of that method here
> }
>
> Since method signatures are very expressive in Perl 6, there should be a
> way of accessing them in the POD without copy & paste.
As I read "=head 3 method..." I also had the idea that semantically more
meaningful directives might be a good idea.
I mean POD uses constructs like headlines, lists, blocks, italic etc.
which all describe _how it looks like_ and not _what it is_.
A head3 might be the headline of a method documentation as well as one
introducing the contact information for the author of a module.
The directive doesn't have much semantics.
Other people might use head2 for documenting methods, what leads to a
pretty inconsistent look of the documentation.
So maybe directives like method, sub, attribute, class etc. might be a
better choice regarding semantics.
Of course those semantics are directly given in the code, so why not use
them as MarkOv proposed?
It's a bit like HTML<->XML, where the former lacks most of the semantics
and makes the information processing - not to speak about a consistent
look over several documents - a lot harder.
I could imagine a semantic documentation in Perl6, that could be
translated to XML/HTML+CSS or to POD(6) for formatting it.
A semantic documentation could also be very useful in IDEs, where the
IDE could clearly (without guessing) determine the documentation for a
certain element.
Also you could automatically test if every method/class/.. has been
documented etc.
Semantics are very useful in documentation, why throw them away?
--
Thomas Wittek
http://gedankenkonstrukt.de/
Jabber: [EMAIL PROTECTED]
