[Discuss] doxygen

[gaf at blu.org (Jerry Feldman)]

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