Re: [jamboost] Doc/Help

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-04-09 18:11:20

On 2002-04-09 at 05:17 PM, david.abrahams_at_[hidden] (David Abrahams) wrote:

>
>----- 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]>
>> >
>> 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.

No offense taken :-) I was just pointing out what I'm accustomed to which
was one of your points. Unfortunately my editor doesn't insert the extra "#"
for comments :-(

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

Well, since we are talking terse, then the obvious minimalist syntax would
be...

# Specifies the documentation for a rule in the current module.
# If called in the global module, this documents a global rule.
#
rule document-rule (
# The name of the rule.
name :
# The documentation for the rule.
docs +
)
{
...
}

Also seems the most direct and to the point. If I remember correctly this is
similar to Lisp docs.

-- grafik - Don't Assume Anything
-- rrivera_at_[hidden] - grafik_at_[hidden]
-- 102708583_at_icq - Grafik666_at_AIM - Grafik_at_[hidden]