[Insight-developers] Run Doxygen? (itk::Math namespace)

[Luis Ibanez]

Hi Brad,

I would be in favor of sticking to a single standard
notation for Doxygen comments.

It will be surprising if there is no automatic way
of dealing with Doxygen indentation in Emacs.

  ... there is certainly one in Vim...        :-)


Doxygen supports at least four different notations
for documentation comments.

   http://www.doxygen.nl/docblocks.html

Mixing them up in the code will simply lead to
confusion.

The files in the Review directory are in...  "review".
If they are not conforming yet to the ITK standards,
we simply have to fix them there before they can
be moved to their final location in a stable directory.


We have bigger and more real problems to deal with
at this point to have to spend time going back on
reviewing the standards of code documentation.

I would rather invest time on fixing our Windows 64
issues, or crawling out of the Copyright nightmare
with ACM licensed code.


    Luis


------------------------------------------------------------
On Mon, Mar 29, 2010 at 8:42 PM, Bradley Lowekamp
<blowekamp at mail.nih.gov> wrote:
> Hello Luis,
>
> I have a preference for that notation because it plays better with emacs. The auto indent, automatically prefixing on a new line etc... The multiline syntax of becomes tedious, to get things lined up correctly while editing the text. Emacs could likely be configured correctly for this style, but I don't know how to do that.
>
> Also I am how to use /** */ with doxygen command line @{ or @cond. Is:
> /** @{ */
> correct?
>
> Lastly, I didn't know that is was specified in the Style Guide in section 3.8:
> http://www.itk.org/Wiki/images/c/c6/ITKStyle.pdf
>
> There also some other files (largely in review), which use this style as well.
>
> Should I change it to conform?
>
> Thanks,
> Brad
>
>
>
>
>
>
> On Mar 29, 2010, at 4:45 PM, Luis Ibanez wrote:
>
>> Hi Brad,
>>
>> I'm wondering why you preferred to use the Doxygen notation
>> of three slashes
>>
>>                                         "/// "
>>
>> for the documentation of the itkMath namespace, instead of
>> the   /**    */     notation that is used in all the rest of the toolkit.
>>
>>
>> Is there any particularity to it ?
>>
>>
>> Otherwise, it probably will be nice to stick to the standard notation.
>>
>>
>>     Thanks for any hint,
>>
>>
>>            Luis
>>
>>
>> ---------------------------------------------------
>> On Mon, Mar 29, 2010 at 3:17 PM, Luis Ibanez <luis.ibanez at kitware.com> wrote:
>>> Hi Brad,
>>>
>>> As we discussed during the Tcon,
>>>
>>> The Doxygen documentation has been regenerated
>>> and posted to the ITK web site.
>>>
>>> The Math namespace seems to be showing
>>> the Macros correctly now:
>>> http://public.kitware.com/Insight/Doxygen/html/namespaceitk_1_1Math.html
>>>
>>>
>>>  Thanks for the committing the fix to the doxygen.config.in file.
>>>
>>>
>>>           Luis
>>>
>>>
>>> ----------------------------------------------------------
>>> On Fri, Feb 26, 2010 at 11:36 AM, Bradley Lowekamp
>>> <blowekamp at mail.nih.gov> wrote:
>>>> Hello Luis,
>>>> Thank you for running that. My main goal was to try to get the templated
>>>> rounding methods documented:
>>>> http://public.kitware.com/Insight/Doxygen/html/namespaceitk_1_1Math.html
>>>> Unfortunately the predefined macro in the Doxygen
>>>> ( itkTemplateFloatingToIntegerMacro) didn't come through for some reason.
>>>> I'll look into this again, making sure it correctly runs locally... again.
>>>> Brad
>>>> On Feb 25, 2010, at 1:03 PM, Luis Ibanez wrote:
>>>>
>>>> Hi Brad,
>>>>
>>>> The Doxygen pages have now been refreshed
>>>> with the documentation that we generated yesterday:
>>>>
>>>> http://public.kitware.com/Insight/Doxygen/html/index.html
>>>>
>>>> If you have a chance, please glance over the pages
>>>> and let us know if you see any problem,
>>>>
>>>>
>>>>     Thanks
>>>>
>>>>
>>>>             Luis
>>>>
>>>>
>>>> -------------------------------------------------------------
>>>> On Wed, Feb 24, 2010 at 12:31 PM, Luis Ibanez <luis.ibanez at kitware.com>
>>>> wrote:
>>>>
>>>> Hi Brad,
>>>>
>>>> Thanks for taking care of these Doxygen issues.
>>>>
>>>> I just started a Doxygen build...
>>>>
>>>> (after updating the source tree)
>>>>
>>>>
>>>> It usually takes about 14 hours to generate the
>>>>
>>>> documentation. So we should be able to see
>>>>
>>>> something online by tomorrow.
>>>>
>>>>
>>>>     Luis
>>>>
>>>>
>>>> ----------------------------------------------
>>>>
>>>> On Wed, Feb 24, 2010 at 10:16 AM, Bradley Lowekamp
>>>>
>>>> <blowekamp at mail.nih.gov> wrote:
>>>>
>>>> Hello,
>>>>
>>>> Could the doxygen be run on the CVS version of ITK?
>>>>
>>>> I was trying to get the doxygen to look right for itkMath. I also ended up
>>>>
>>>> updating the PREDEFINES for other macros which are used to generate methods
>>>>
>>>> in headers. While I ran this config with doxygen 1.6.1 locally, the official
>>>>
>>>> doxygen is only run with 1.5.8 so I would like to ensure compatibility.
>>>>
>>>> http://public.kitware.com/cgi-bin/viewcvs.cgi/Utilities/Doxygen/doxygen.config.in?root=Insight&r1=1.37&r2=1.38&sortby=date
>>>>
>>>> http://public.kitware.com/cgi-bin/viewcvs.cgi/Code/Common/itkMath.h?root=Insight&r1=1.11&r2=1.12&sortby=date
>>>>
>>>> Thanks,
>>>>
>>>> Brad
>>>>
>>>> ========================================================
>>>>
>>>> Bradley Lowekamp
>>>>
>>>> Lockheed Martin Contractor for
>>>>
>>>> Office of High Performance Computing and Communications
>>>>
>>>> National Library of Medicine
>>>>
>>>> blowekamp at mail.nih.gov
>>>>
>>>>
>>>>
>>>>
>>>>
>>>
>
>