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
Mark Overmeer wrote:
We had a private discussion about this already three years ago: I
fully disagree! If the code and the documentation are not entangled,
why do you want to put them in the same file? Why do you put them in
the same distribution even?
No, the documentation is all about
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
* 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
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
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
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
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
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
* 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?
10 matches
Mail list logo
