doxygen warning / nested comments

[Stephan Bergmann]

On 06/18/2014 05:16 PM, Lionel Elie Mamane wrote:
> Noticed in my build:
>
> /home/master/src/libreoffice/workdirs/libreoffice-4-3/udkapi/com/sun/star/io/FilePermission.idl:76:warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 25)
>
> This seems to be a message from doxygen. This looks like the
> documentation of FilePermission will be blank because the content is
> "skipped" because taken as part of comment... However,
> http://api.libreoffice.org/docs/idl/ref/structcom_1_1sun_1_1star_1_1io_1_1FilePermission.html
> looks reasonable, so maybe this is a red herring.

No idea with exactly what 4.2 sources and what toolchain 
<http://api.libreoffice.org/docs/idl/ref> has been generated, but at 
least recent Doxygen 1.8.6 and 1.8.7 indeed would miss documentation of 
FilePermissions.

Looks like Doxygen deliberately tracks nested /* ... */ comments within 
/** ... */ comments (cf. g_nestingCount in src/commentcnv.l), maybe to 
support such comments inside @code blocks as discussed at 
<https://sourceforge.net/p/doxygen/mailman/doxygen-users/thread/ad6e09750605081949w8555322u711dbb4eb8dc0af5@mail.gmail.com/> 
"[Doxygen-users] how to add c-style comments inside @code?"  But I did 
not find any rationale for that in the Doxygen documentation at 
<http://www.stack.nl/~dimitri/doxygen/manual/index.html>.

Anyway, worked around now on master and libreoffice-4-3, so future 
updates of <http://api.libreoffice.org/docs/idl/ref> should also be safe.

Stephan