Boost logo

Boost-Build :

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.

@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

>> 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, david.abrahams at, gregod at, cpdaniel at, john at