Re: POD - Code entanglement
For what it's worth, I'm a fan of the notation that NaturalDocs uses. Function: Multiply Multiplies two integers. Parameters: x - The first integer. y - The second integer. Returns: The two integers multiplied together. See Also: Divide http://www.naturaldocs.org/ (...which happens to be written in Perl.) On 6/14/07, Mark Overmeer [EMAIL PROTECTED] wrote: * Thom Boyer ([EMAIL PROTECTED]) [070614 15:49]: the existing S26, say things like: =Method the method synopsis goes here =begin Parameters =item foo is the fooiest parameter =item bar is the barstest parameter =end Parameters Where is the link with the code? That's the point: there is no automatic checking/avoidance of repetition. Besides, your example is not defined by S26: one can decide to use the tags, someone else chooses other names, and they then cannot be combined into one nice homogeneous set of pages. That's a horror! And if you really like above syntax, why not define =method the method synopsis goes here =option foo is the fooiest parameter =default foo 10 =requires bar is the barstest parameter Which is close to how OODoc is extending POD for Perl5. IMO We can (should) do better for Perl6. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: POD - Code entanglement
Moritz Lenz:
=begin pod
=head3 Cmethod 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]
Re: POD - Code entanglement
* Thomas Wittek ([EMAIL PROTECTED]) [070614 15:18]: So maybe directives like method, sub, attribute, class etc. might be a better choice regarding semantics. See OODoc::Parser::Markov 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. In HTML, you have logical markup as well: EM, STRONG, KEY, CODE, etc With id and class, you can make any annotation you like: div class=method my_method OPTIONS This is the description of a method. /div I love the power of CSS. I could imagine a semantic documentation in Perl6, that could be translated to XML/HTML+CSS or to POD(6) for formatting it. The nicest thing would be that the semantic docs become part of the parse tree, which then (using standard introspection) can be used to generate manual pages, natively into POD, roff, HTML, whatever. I see no reason why entangled docs are so hard to parse for Perl6, as Damian arguments. Even it being difficult is not a good reason to make the life of all programmers harder. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: POD - Code entanglement
Thomas Wittek skribis 2007-06-14 17:18 (+0200):
So maybe directives like method, sub, attribute, class etc. might be a
better choice regarding semantics.
Yes, a better choice indeed. But I would still not be happy with it,
because there would still be a lot of code duplication.
method foo (:$bar = 5) { ... }
I don't want to have to mention *again* that the thing is a method,
and that it is called foo, that it has a named argument identified
as $bar, which defaults to 5.
This is why I (long time ago) suggested is documented. Like Mark, I do
not really care about the actual syntax much:
method foo is documented(Foos its argument interactively)
(
:$bar = 5 is documented(Object to be fooed),
# I'm not sure about the precedence of is.
) {
...
}
The backtick is rather cute and saves a lot of typing. It's like a
comment (#), but ends up as *external* documentation. That's nice.
Semantics are very useful in documentation, why throw them away?
Why not have both? With normal POD as suggested by Damian, you could
still generate it from something else. A few macros could help ignore
the inline documentation.
--
korajn salutojn,
juerd waalboer: perl hacker [EMAIL PROTECTED] http://juerd.nl/sig
convolution: ict solutions and consultancy [EMAIL PROTECTED]
Re: POD - Code entanglement
On 6/14/07, Thomas Wittek [EMAIL PROTECTED] wrote: 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. Actually, that's incorrect. HTML is a markup language with a particular set of elements, some of which have semantic meaning attached and some of which don't. XML, on the other hand, is a means of writing your own markup languages; this has two consequences in this context: 1. It is just as easy—if not easier—to have an XML dialect containing elements with absolutely no meaning. 2. Even if the dialect contains only elements with well-defined semantics, it's still completely meaningless to a generic XML parser. A parser must be intimately familiar with the dialect to understand that any element has semantic meaning. If you were referring to XHTML vs. HTML, I would like to point out that XHTML 1.0 is merely a reformulation of HTML 4.01 in XML. The elements and their semantics are unchanged. XHTML 1.1 modularizes the DTD and adds a few Ruby (annotation, obviously, not language) elements, in addition to a few other minor changes. As for XHTML 2.0, that's still a long way off. :-) -- Aankhen (We have no branches.)
Re: POD - Code entanglement
Mark Overmeer schreef: The nicest thing would be that the semantic docs become part of the parse tree, which then (using standard introspection) can be used to generate manual pages, natively into POD, roff, HTML, whatever. I like to call them: lexical comments. -- Groet, Ruud
Re: POD - Code entanglement
Thomas Wittek wrote:
Moritz Lenz:
=begin pod
=head3 Cmethod 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.
That may be my fault, I didn't care to look if there was a more semantic
way to describe it.
I mean POD uses constructs like headlines, lists, blocks, italic etc.
which all describe _how it looks like_ and not _what it is_.
Headlines, lists and blocks are IMHO semantic markup.
If I'd say Huge font in bold that'd be descriptive rather than
semantic markup.
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.
That doesn't make a headline worthless. It just shouldn't be abused the
way I did it ;)
--
Moritz Lenz
http://moritz.faui2k3.org/ | http://perl-6.de/
signature.asc
Description: OpenPGP digital signature
Re: POD - Code entanglement
Thomas Wittek wrote: I mean POD uses constructs like headlines, lists, blocks, italic etc. which all describe _how it looks like_ and not _what it is_. I think Damian would take exception to that statement. He worked quite hard to make sure that POD describes _meaning_ rather than _appearance_. He even renamed B from bold to basis, I from italic to important, and U from underline to unusual. All of those are fairly odd choices, with the possible exception of important, but they were clearly made with an eye to backwards compatibility of POD while changing people's focus from how it looks to 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. Well, I'd argue that head3 has plenty of semantics. It's a level-3 header. How that's rendered is decided elsewhere. I think the issue is not that head3 is insufficiently semantic, it's just that you want something that's even more specific. And POD 6 was designed with exactly that kind of thing in mind. You can, according to the existing S26, say things like: =Method the method synopsis goes here =begin Parameters =item foo is the fooiest parameter =item bar is the barstest parameter =end Parameters Furthermore, the Perl parser actually *keeps* the POD chunks, so you can access all that information in the context of the Perl parse. Damian and Larry were clearly laying the groundwork for exactly the sort of javadoc-ish features you are asking for. =thom - The supreme irony of life is that hardly anyone gets out of it alive. --Robert A. Heinlein [Job: A Comedy of Justice]
Re: POD - Code entanglement
* Thom Boyer ([EMAIL PROTECTED]) [070614 15:49]: the existing S26, say things like: =Method the method synopsis goes here =begin Parameters =item foo is the fooiest parameter =item bar is the barstest parameter =end Parameters Where is the link with the code? That's the point: there is no automatic checking/avoidance of repetition. Besides, your example is not defined by S26: one can decide to use the tags, someone else chooses other names, and they then cannot be combined into one nice homogeneous set of pages. That's a horror! And if you really like above syntax, why not define =method the method synopsis goes here =option foo is the fooiest parameter =default foo 10 =requires bar is the barstest parameter Which is close to how OODoc is extending POD for Perl5. IMO We can (should) do better for Perl6. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
