[25.0.0.9] Doc Comments not parsed correctly

[Liberty]

I often use //! to start doc comments, and unfortunately v25 seems to wrongly parse them.
When I checked a bit, I saw that only /*! works as expected, /** does not separate brief and body, /// is treated like a normal multiline comment, and //! picks up the '!' as part of the comment.
I also noticed that a doc comment with line-continuation (demo4) is only using the last line, but that construct, while legal, I would never use

(I use Win64)

Code: [Select]

/*!
 * Demo Function
 * 
 * This function is a demo
 * 
 * \param x the input
 * \return the return
*/
int demo( int x);

/**
 * Demo Function
 * 
 * This function is a demo
 * 
 * @param x the input
 * @return the return
*/
int demo1( int x);

///
/// Demo Function
/// 
/// This function is a demo
///
/// \param x the input
/// \return the return
int demo2( int x);

/// Demo Function \
This function is a demo \
 \
 @param x the input \
 @return the return
int demo4( int x);

//!
//! Demo Function
//! 
//! This function is a demo
//!
//! \param x the input
//! \return the return
int demo3( int x);


[Dennis]

I will look into this next week.

As a work-around, you can turn off the following option to get back to the v24 behavior.

Document > C/C++ Options... > Comments > Documentation comments > [ ] Store documentation comments when tagging

You will need to rebuild your workspace tag file after changing that setting.

[Liberty]

Thank you.

Here is another problem:

Code: [Select]

/*!\brief Test for Completion
 *        Doing our best
 *
 * \param start Time in ms for start
 * \param end Time in ms for end
 *
 * \note This is a test
 * \details Can be called as follows:
 * @code
 * void test() {
 *
 *    // run the test()
 *    completion_test( 1, 2);
 * }
 * @endcode
 */
void completion_test( int start, int end);

This parses correctly once you remove the second line, so it seems that seeing a \brief with multiple lines is tripping the parser.

I also noticed two other things:
 - the single empty line in the code example looks like three lines high
 - on my monitor, the tagging tool window sometimes gets very wide with long paragraphs, making them difficult to read. I have a 38" monitor, so SE has space for three files side by side, each about 120 characters wide. I would like to see a width limit somewhere around 150 characters, unless some @code region demands more.

[Dennis]

Case 1:  /*!  - The one that works.

Case 2:  /**  Because Doxygen is Doxygen and JavaDoc is JavaDoc, we have a hidden option to
             interpret JavaDoc style comments as Doxygen, even if they do not use the Doxygen /*!
             introduction sequence.

             Macro > Set Macro Variable... > def_doxygen_all = 1

             That said, I feel like that comment should have separated those two paragraphs, even if
             it does not interpret the first line as a "Brief" in JavaDoc mode.  So I will look into that.

Case 3:  "///" is the introduction sequence for MicroSoft-style XMLDoc comments.
             We would have to introduce another option to interpret them as Doxygen.

Case 4: Line continuations.  Let's just skip this one.

Case 5: "//!" -- Definitely a bug, I will look into fixing this for 25.0.1

Case 6: Yes, numerous bugs here, I don't think any of them are new though.

So I'm going to file a defect to look into these.  I expected when we transitioned to storing comments in the tag database
that there would be a few hiccups along the way.

[Dennis]

Quick update:  All these bugs, even the line continuations case will be fixed for 25.0.1.

In addition, the issue with long paragraphs being formatted excessively wide will be addressed in the next hot fix.

[Liberty]

Nice to hear about the fixes.

I did not realize how messy document comments can become. I would assume that one is not mixing doxygen/javadoc/xmldoc within a project, so maybe the cleanest setup would be to have a project level option to select the style?