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
> 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
>3. Doesn't show up in debug output when not being scanned
>Also, please see what's happening in the Python world:
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.
The name of the rule.
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
>> 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
>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
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
>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]
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