From: David Abrahams (david.abrahams_at_[hidden])
Date: 2002-04-09 17:17:11
----- Original Message -----
From: "Rene Rivera" <grafik666_at_[hidden]>
> On 2002-04-08 at 02:59 PM, david.abrahams_at_[hidden] (David Abrahams)
> >----- Original Message -----
> >From: "Rene Rivera" <grafik666_at_[hidden]>
> >> How do you consider the comment "#" style of documentation a better
> >> programmer interface?
> >1. Far less redundancy, i.e no need to:
> > b. say that it is a rule as opposed to a variable
> yes. But it asumes that you specify variables with "VAR = VALUE ;"
I predict that there will be little need for direct access to other
modules' variables. However, if we do need it, I don't think
# comment about var
.var = ;
> > c. use special markings to denote arguments
> That's not a difference. They both use special markings.
You don't neccessarily need them if you are going to parse the file
anyway, and I have a strong preference for a system which just "does the
right thing" without the need for extra cruft in the comments except in
> What I actually prefer is, and yes these are comemnts :-)
> Specifies the documentation for a rule in the current module.
> If called in the global module, this documents a global rule.
> @param name
> The name of the rule.
> @param docs
> The documentation for the rule.
> rule document-rule ( name : docs + )
> Which is the Doxygen/Javadoc style, which is what I'm familiar with,
> imagine many other people as well. And yes it would require adding
"##" as a
> new comment syntax! So Dave how hard would it be to implement that
Harder than neccessary. I'm sorry to be blunt about it, but I consider a
change like that frivolous: you saved exactly 3 characters above. I
would have to train emacs to recognize these comments, too.
Also, I really dislike the use of @directive unless absolutely
neccessary. /My/ interface to the code is as important as the help
system for users, and I don't see any reason to read/write @param. This
is part of the reason I don't use doxygen. We could pick a nice, terse
comment style and the system could be trained to recognize it. for
# Specifies the documentation for a rule in the current module.
# If called in the global module, this documents a global rule.
# name -- The name of the rule.
# docs -- The documentation for the rule.
rule document-rule ( name : docs + )
Because the system is parsing the code anyway, it knows that 'name' and
'docs' are parameter names.
> > The same about variables. Module
> >docs might require some special syntax ("#module" as the first line
> How about taking the first doc-comment in the module?
I like that idea: a simple, terse protocol.
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk