Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Multiline Comment Blocks (Origin: bugzilla #675766) #4699

Closed
doxygen opened this Issue Jul 2, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@doxygen
Copy link
Owner

doxygen commented Jul 2, 2018

status RESOLVED severity minor in component documentation for ---
Reported in version unspecified on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

On 2012-05-09 17:12:47 +0000, Mihai Todor wrote:

Multiline comment blocks inside functions don't behave as expected when inserted into the body of a function / method. I have not performed exhaustive tests of this issue, but, for example, the comment block:

class test
{
void X()
{
/// Required comment

    /**
    Test comment:
    - Stuff1 @f$ x @f$
  • Stuff2 @f$ y @f$
    • Stuff 3 @f$ \mathbb{Z}_n^* @f$
      */
      }
      };

will render much different than this one:

class test1
{
void X()
{
/// Required comment

    /**
    * Test comment:
    * - Stuff1 @f$ x @f$
    • Stuff 3 @f$ \mathbb{Z}_n^* @f$
      */
      }
      };

Things to note:

  • It renders badly if the intermediary "*"s are missing (and it does not display the formulas);
  • It does not reproduce if the big comment block is not preceded by some other (rendered) comment;
  • It messes up even if I use /// before every line of the comment block. The only version that seems to work properly is the one with the intermediary "*"s;
  • It's annoying, because intermediary "*"s are redundant and not every text editor adds them automatically.

On 2012-05-09 17:15:22 +0000, Mihai Todor wrote:

Some tab characters messed up the code formatting when I submitted the bug. Here is the properly indented code (I hope):

class test
{
void X()
{
/// Temporary variable

  /**
  Test comment:
  - Stuff1 @f$ bla1 @f$
  - Stuff2 @f$ bla2 @f$
  	- Stuff 3 @f$ teeeeest @f$
  */

}
};

class test1
{
void X()
{
/// Temporary variable

  /**
  * Test comment:
  * - Stuff1 @f$ bla1 @f$
  * - Stuff2 @f$ bla2 @f$
  *	- Stuff 3 @f$ teeeeest @f$
  */

}
};

On 2012-05-09 19:05:13 +0000, Dimitri van Heesch wrote:

Can you please attach the example along with the config file in a zip or tar. That ways the tabs/spaces are preserved. Note that intermixing tabs and spaces requires TAB_SIZE to be properly set. Maybe that is part of the problem?

On 2012-05-09 20:06:35 +0000, Mihai Todor wrote:

Created attachment 213767
Test files meant to illustrate the described issue

On 2012-05-09 20:07:21 +0000, Mihai Todor wrote:

Hi Dimitri,

I don't think that TAB_SIZE is the issue here. Please find attached an archive containing examples with (more or less) consistent formatting.

You will find several code blocks inside, meant to illustrate multiple issues that I discovered. I hope this helps.

Best regards,
Mihai Todor

On 2012-05-18 09:56:08 +0000, Dimitri van Heesch wrote:

Hi Mihai,

Looking at your example, most issues come from Markdown support. See http://www.doxygen.org/markdown.html

Try setting MARKDOWN_SUPPORT to NO and you'll see that you get the old behavior back. I'll have a look if any of your examples should have worked taking the Markdown rules into account.

On 2012-05-18 20:16:31 +0000, Mihai Todor wrote:

Hi Dimitri,

Thank you for investigating and clarifying this issue. While, indeed, the main issue that I reported is caused by markdown, I prefer to use the workarounds than to drop the markdown support completely. Perhaps, in the future, the integration will have fewer issues.

On 2012-07-08 12:45:41 +0000, Dimitri van Heesch wrote:

Confirmed. The fix for 679331 also solves these issues, so I'll mark this as duplicate.

*** This bug has been marked as a duplicate of bug 679331 ***

@doxygen doxygen closed this Jul 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.