[Discuss] doxygen

[John Abreau]

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
>



-- 
John Abreau / Executive Director, Boston Linux & Unix
AIM abreauj / JABBER jabr at jabber.blu.org / YAHOO abreauj / SKYPE zusa_it_mgr
Email jabr at blu.org / WWW http://www.abreau.net / PGP-Key-ID 0xD5C7B5D9
PGP-Key-Fingerprint 72 FB 39 4F 3C 3B D6 5B E0 C8 5A 6E F1 2C BE 99