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]