Re: [boost] [documentation] doxygen tags and ALIASES.

Subject: Re: [boost] [documentation] doxygen tags and ALIASES.
From: Barend Gehrels (barend_at_[hidden])
Date: 2011-03-23 13:44:09

>> We have many of these.
>> @return is a standard Doxygen parameter, as is @param and I think
>> @throws.
>>
>> Also notes and remarks are standard Doxygen.
> Yes, I know. The question is how to define the missing tags so the look is coherent and the tags are not mixed. As I understand doxygen takes any none tagged line as part of the detailed description (except the first one) and move the tagged lined after the detailed description.

I'm afraid I don't understand what you're trying to achieve. The 
doxygen-tags are not meant to give a coherent look, they are meant to 
generate convenient documentation. So why not mixing tags there?

> BTW, where can I find the ALIAS you use?

I sent the doxygen-file-link earlier. In another thread I mentioned the 
page describing how we document, so I'll repeat that here:

http://bit.ly/i2zGfC

Is this what you are missing?

> I was not only thinking on template parameters requirements but also 
> to run-time requirements (i.e. pre-conditions). the predefined @pre 
> should work if we reach to get a coherent lock.

Again, of course it looks coherent within Doxygen but the problem is: 
what to do with that afterwards. We could define a
\qbk{[heading Preconditions]
The precondion is: foo
}

Generating a nice looking Quickbook piece. But in the Doxygen-C++ 
section it does not really look coherent.

>
>> An examples is normally not one line of code but a complete
>> program, and should not be inside the Doxygen documentation because it
>> has to be a compiled example, to avoid errors slipping through.
> I was thinking to basic examples, not complete programs. For complete programs I guess we should use reference to external documentation, or is there a better way?

Complete programs are the best basic examples. See our example e.g. here:

http://bit.ly/en9JsR

First I used snippets but Mateusz convinced me that it should really be 
complete examples including headerfiles. And I agree completely now.

This is the same way cplusplus does it , e.g.

<http://www.cplusplus.com/reference/algorithm/sort/>

which is really useful.

>> This also depends on the tools which you are using to
>> create QuickBook.
> Sorry, I don't understand.

I mean, Doxygen-tags themselves are not useful. Doxygen creates 
HTML-documents which are basically useful but rejected by most Boost 
folks. But Doxygen can also create XML-documents which can be 
interpreted by tools as XSLT, or (in our case) a C++/rapidxml 
implemented tool, which parses the XML and generates QuickBook.

 From QuickBook you go all the way back to HTML, but that is standard.

See also the link I pasted above.

Regards, Barend

-- 
Barend Gehrels
http://about.me/barendgehrels