[Discuss] doxygen

[me at mattgillen.net (Matthew Gillen)]

The bigger issue with respect to doxygen is that the two comment styles 
have different purposes (at least the last time I read the doxygen 
documentation, which admittedly was many years ago).

The line oriented comments are used for short descriptions (e.g. for the 
compact table of functions and classes).  The block comments are used 
for the 'detailed' description.


Matt

On 7/13/2011 10:54 PM, John Abreau wrote:
> The // comments are line-oriented, not block-oriented.
> It's not that they don't nest, it's that the very concept
> of nesting is meaningless in their context.
>
>
>
> On Wed, Jul 13, 2011 at 5:22 PM, Jerry Feldman<gaf at blu.org>  wrote:
>> This is a well known feature  C and C++. It is not a bug, it is well
>> defined in the C and C++ standards.
>> The // comments do not nest either.
>>
>> On 07/13/2011 03:18 PM, John Abreau wrote:
>>> One common gotcha with the /* blaaa */ style comments is that
>>> they don't nest. So if you have a block
>>>
>>>      foo() {
>>>         int i;
>>>         printf("Hello world!\n");
>>>         i = 27; /* need to initialize this */
>>>         printf("%d\n", i);
>>>         printf("All done!\n");
>>>      }
>>>
>>>
>>> and you comment out a chunk
>>>
>>>
>>>      foo() {
>>>         int i;
>>>         printf("Hello world!\n");
>>>         /*
>>>         i = 27; /* need to initialize this */
>>>         printf("%d\n", i);
>>>         */
>>>         printf("All done!\n");
>>>      }
>>>
>>> The first instance of */ closes the comment, and the "printf("%d\n", i);"
>>> that you thought you had commented out is actually not commented out,
>>> and chaos ensues.
>>>
>>>
>>>
>>> On Thu, Jul 7, 2011 at 9:30 AM, Stephen Adler<adler at stephenadler.com>  wrote:
>>>> Thanks for the reply Matt. And as software goes, the devil is in the
>>>> details....
>>>>
>>>> In doxygen, you have a couple of syntax forms you can use
>>>>
>>>> /// blaaa
>>>> //! blaaa
>>>>
>>>> /** blaaa */
>>>> /*! blaaa */
>>>>
>>>> I hate it when I'm given options to choose from because I don't know
>>>> which one to choose other than flip a coin. Is there any advantages or
>>>> disadvantages to using either form?
>>>>
>>>> thanks. Steve.
>>>>
>>>> On Wed, 2011-07-06 at 09:32 -0400, Matthew Gillen wrote:
>>>>> On 07/05/2011 09:27 PM, Stephen Adler wrote:
>>>>>> Guys,
>>>>>>
>>>>>> I want to use an automated web'izing documentation tool like doxygen for
>>>>>> a software project I'm working on. I'm wondering what's the use case for
>>>>>> this is. What I mean by use case is the way one adds the html generation
>>>>>> into the software development cycle. This question may be too simplistic
>>>>>> but maybe there are some general rules which would make life easy for me
>>>>>> that I wouldn't think of when I start using a tool like doxygen. For
>>>>>> example, does one only generate html documentation output when one
>>>>>> prepares the code for a release or version tag? Does one include a
>>>>>> documentation target in the make file so one can type 'make
>>>>>> documentation' How often do you generate the documentation? After each
>>>>>> make? etc. etc. If there is a web resource I should read through, I'd
>>>>>> greatly appreciate the url and any comments you guys may have.
>>>>> Typically what is done in my projects is that our make system has a
>>>>> 'doc' target that runs doxygen.  If we have an autobuild, we will go
>>>>> ahead and include the documentation in that and have the results hosted
>>>>> in an accessible location (intranet web server).  Don't include the
>>>>> 'doc' target in the default build, since most developers won't need a
>>>>> local copy; the nightly version of the API docs from the autobuild are
>>>>> always sufficient.
>>>>>
>>>>> The doc target helps with devs being able to test their in-line
>>>>> documentation, and if you've got developers outside a firewall or are
>>>>> otherwise difficult w.r.t. the intranet server.
>>>>>
>>>>> HTH,
>>>>> Matt
>>>>> _______________________________________________
>>>>> Discuss mailing list
>>>>> Discuss at blu.org
>>>>> This message was delivered to adler at stephenadler.com
>>>>> http://lists.blu.org/mailman/listinfo/discuss
>>>>>
>>>>
>>>> _______________________________________________
>>>> Discuss mailing list
>>>> Discuss at blu.org
>>>> This message was delivered to jabr at blu.org
>>>> http://lists.blu.org/mailman/listinfo/discuss
>>>>
>>>
>>>
>>
>>
>> --
>> Jerry Feldman<gaf at blu.org>
>> Boston Linux and Unix
>> PGP key id: 537C5846
>> PGP Key fingerprint: 3D1B 8377 A3C0 A5F2 ECBB  CA3B 4607 4319 537C 5846
>>
>>
>>
>> _______________________________________________
>> Discuss mailing list
>> Discuss at blu.org
>> This message was delivered to abreauj at gmail.com
>> http://lists.blu.org/mailman/listinfo/discuss
>>
>>
>
>
>