[Discuss] doxygen

[abreauj at gmail.com (John Abreau)]

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
>
>



-- 
John Abreau / Executive Director, Boston Linux & Unix
GnuPG KeyID: 0xD5C7B5D9 / Email: abreauj at gmail.com
GnuPG FP: 72 FB 39 4F 3C 3B D6 5B E0 C8 5A 6E F1 2C BE 99