Re: [jamboost] Doc/Help

From: Rene Rivera (grafik666_at_[hidden])
Date: 2002-04-09 10:22:39

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:
> a. write the name of the rule again

yes.

> b. say that it is a rule as opposed to a variable

yes. But it asumes that you specify variables with "VAR = VALUE ;"

> c. use special markings to denote arguments

That's not a difference. They both use special markings.

>2. Already familiar

yes.

>3. Doesn't show up in debug output when not being scanned

yes.

>Also, please see what's happening in the Python world:
>
>http://aspn.activestate.com/ASPN/Mail/Message/python-dev/1097730

Interesting.

On 2002-04-09 at 11:35 AM, ghost_at_[hidden] (Vladimir Prus) wrote:

>David Abrahams wrote:
>
>> I really prefer scanning files to extract doc from comments; it could
>> solve the function signature problem pointed out above. I'd like to be
>> able to write:
>>
>> # Specifies the documentation for a rule in the current module.
>> # If called in the global module, this documents a global rule.
>> #
>> # <arg>name -- the name of the rule
>> # <arg>docs -- The documentation for the rule
>> rule document-rule ( name : docs + )
>> {
>> ...
>> }
>
>I prefer it too.

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?

>> In summary, the UI design is excellent. 
>
>Agree! This makes the whole system much more easy to use.
>
>> I'd like it a little better if
>> the programmer interface were smoother.
>
>After some thinking and then looking at the files attached to
>http://groups.yahoo.com/group/jamboost/message/732
>I think that find rule docs should be easy.

I never said it was hard ;-) Just not as easy as what I did.

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

> Note that doxygen, for example, also require special command to 
>mark file docs. And we'll only need a way to shut 
>"found such much targets" messages from jam.
>
>If we don't take this route (in general or just not now), I'd appeciate
some 
>changes to doc formatting. For example, enumerated list in docs for 
>regex.split become a straight line in output. I believe it possible to just 
>start a new line on elements matching "[-0-9]*)".

I, again, prefer immitating Doxygen in this... use "-" at the start to
indicate a list item, "-#" to indicated an enumerated list item.

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