"Formatting" in ADL Header comments


#1

(some of) the ADL Headers contain a lot of “formatting” tags; eg,

/** @brief Configure the synchronous/asynchronous mode settings.
         *  @param[in] The \link adl_busIOCtl() Param\endlink of adl_busIOCtl() is defined as a pointer on #adl_busEvt_t.\n
                       When this parameter is set to a value different of <b><code>NULL</code></b>, adl_busWrite() and adl_busRead() behaviour become asynchronous.\n
                       When it is set to <b><code>NULL</code></b>, read/write operations are synchronous (default value)\n\n
         *  @note Available for the SPI and I2C Bus only.\n\n
         */

These make them hard to read in a plain text editor! :frowning:

If Wavecom are going to do this, the M2MStudio should be able to display it properly - otherwise, don’t do it!

Some of the lines are also excessively long - which also makes them hard to read. :frowning:


#2

Hiya,

The tags are Deoxygen code documentation tags.

In fact, if you look at the marked-up comments in the header files, and the API documentation, you will find that they are virtually identical. It looks like Wavecom simply run their header files through Deoxygen and there’s the API documentation.

And I agree, it makes the comments hard to read. Eclipse is smart enough to parse JavaDoc (similar, but not the same as Deoxygen) formatted comments and display them appropriately. I installed the eClox Deoxygen plugin in the hope that it would parse these comments in the same manner as JavaDoc, but no joy.

I can now however parse all my source and headers into a set of HTML documents, complete with pretty call and file dependancy graphs…

ciao, Dave


#3

You can turn on Doxygen tags highlighting thanks to the Window > Preferences > C/C++ > Editor > Documentation tool comments setting.
However, it doesn’t solve the “long lines” issue.


#4

Hiya,

Ta for that.

ciao, Dave