After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 756185 - Multiline //!< behavior changed
Multiline //!< behavior changed
Status: RESOLVED FIXED
Product: doxygen
Classification: Other
Component: general
1.8.9.1
Other Linux
: Normal normal
: ---
Assigned To: Dimitri van Heesch
Dimitri van Heesch
Depends on:
Blocks:
 
 
Reported: 2015-10-07 13:16 UTC by Stephan Beyer
Modified: 2016-12-29 18:46 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
foo.h (123 bytes, text/x-chdr)
2015-10-07 18:29 UTC, Stephan Beyer
Details
doxygen.cfg (101.59 KB, text/plain)
2015-10-07 18:30 UTC, Stephan Beyer
Details

Description Stephan Beyer 2015-10-07 13:16:01 UTC
Hi,

in 1.8.8, this example:

      int foo; //!< This is an example member
               //!< with a multiline comment

generated

  "This is an example member with a multiline comment"

In 1.8.9.1 it generates

  "This is an example member < with a multiline comment"

Replacing the last //!< by //! is a workaround for the
issue but the new behavior is unintuitive and does not
look intentional.

Regards
  Stephan
Comment 1 albert 2015-10-07 15:48:00 UTC
I tried to reproduce the problem, but failed (placed the code in a .h file)

Can you please attach a self-contained example (source+config file in a tar or zip) that allows us to reproduce the problem?
Comment 2 Stephan Beyer 2015-10-07 18:29:20 UTC
Created attachment 312844 [details]
foo.h

Code example
Comment 3 Stephan Beyer 2015-10-07 18:30:27 UTC
Created attachment 312845 [details]
doxygen.cfg

The default config file with MULTILINE_CPP_IS_BRIEF = YES
Comment 4 Stephan Beyer 2015-10-07 18:56:18 UTC
Two sorries:

1. Sorry for sending two mails, I thought Bugzilla would create one post with two attachments.

2. The behavior did *not* change between the noted versions. (I found this behavior in some bigger series of changes, in one MULTILINE_CPP_IS_BRIEF was changed from NO to YES.)
Comment 5 albert 2015-10-11 17:07:42 UTC
The problem here has to do with the setting of MULTILINE_CPP_IS_BRIEF. In case this is set to YES the reported problem appears, when the MULTILINE_CPP_IS_BRIEF is set to NO the problem does not appear.

From the documentation in the in the Doxyfile (doxygen.cfg):
# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
# multi-line C++ special comment block (i.e. a block of //! or /// comments) as
# a brief description. This used to be the default behavior. The new default is
# to treat a multi-line C++ comment block as a detailed description. Set this
# tag to YES if you prefer the old behavior instead.


So it look to me that this is not a bug or it is a non expected side effect.
In the later case and looking in scanner.l (currently line 62015) the "problem" might be overcome bu changing the line:
<DocLine>[^\n]*"\n"[ \t]*"//"[/!]       { // continuation of multiline C++-style comment
into
<DocLine>[^\n]*"\n"[ \t]*"//"[/!][<]?   { // continuation of multiline C++-style comment
though I don't know if this will have side effects.
Comment 6 Dimitri van Heesch 2016-10-09 11:11:29 UTC
I think Albert's proposal is an improvement indeed.
Should be corrected in the next GIT update.
Comment 7 Dimitri van Heesch 2016-12-29 18:46:05 UTC
This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.13. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information 
that you think can be relevant (preferably in the form of a self-contained example).