Re: [jamboost] Doc/Help

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

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

>
>----- Original Message -----
>From: "Rene Rivera" <grafik666_at_[hidden]>
>
>> 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.
>
>Yes! As long as I can write it:
>
># Specifies the documentation for a rule in the current module.
># If called in the global module, this documents a global rule.
>rule document-rule (
> name # The name of the rule.
> : docs + # The documentation for the rule.
> )
>{
> ...
>}

I figured you'd suggest that ;-] I typed that and then changed it because I
realized that it would be easier to code when the comment is always before
the item.

>I think we may need something like my previous suggestion eventually,
>for when argument documentation grows large. But let's cross that bridge
>when we come to it.

Like in Doxygen & Javadoc, argument documentation should NOT grow too large.
If it does then you should put it as part of the regular comment, hopefully
in a good prose style!

...I suggest we start using that style of docs now! I'll put the effort into
doc.jam to parse it. But not until the weekend.

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