Re: [jamboost] Doc/Help

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)
wrote:
>
> >
> >----- 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 = ;

is burdensome.

> > 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
unusual cases.

> 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,
and I
> 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
comment
> style?

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
example:

# 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
in
> >comment?).
>
> How about taking the first doc-comment in the module?

I like that idea: a simple, terse protocol.

-Dave