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

Code tag in XML doc comments destroys line breaks (Origin: bugzilla #673660) #4655

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

Comments

Projects
None yet
1 participant
@doxygen
Owner

doxygen commented Jul 2, 2018

status RESOLVED severity normal in component general for ---
Reported in version 1.8.0 on platform Other
Assigned to: Dimitri van Heesch

On 2012-04-06 19:18:53 +0000, Markus Ewald wrote:

Assuming I had one of my classes documented with the following XML doc comment:

///

Timer for games that advances time in fixed steps
///
///
/// Frame rate independent movement can be implemented in two ways: either via
/// time scaling or via time stepping. Time scaling will scale the movements of all
/// objects in a game by the amount of time passed since the last frame. Time stepping
/// advances time in fixed steps, multiple times if more time has passed than the length
/// of a single step.
///
///
/// This timer is intended for the stepped approach. The advantages are simpler updating,
/// improved stability of physics simulations (most physics engines go haywire if time
/// jumps by a large amount) and the guarantee for identical rounding errors for all
/// players in a multi-player game.
///
///
///
/// steppedTimer.Reset();
/// while(!this->quitRequested) {
/// GameTime timeStep;
/// while(steppedTimer.TryAdvance(timeStep)) {
/// UpdateAll(timeStep);
/// }
///
/// GameTime frameTime = steppedTimer.GetFrameTimeAndReset()
/// DrawAll(frameTime);
///
/// RunMessagePump();
/// }
///

///
class Stepped Timer { /* ... */ };

This will end up as three lines of code, everything being concatenated together until a blank line is encountered.

Microsoft's guide for XML documentation comments (which might or might not apply when using Doxygen) has this precise constellation of tags as an example: http://msdn.microsoft.com/en-us/library/9w4cf933.aspx

It would be great if Doxygen could preserve line breaks the same way other XML doc comment processors (eg. Visual Studio, Sandcastle) do.

Ideally, it would scan for the least indented line within the code tags and adjust indentation according to that, then putting everything in a

 section for HTML output.

On 2012-05-26 16:51:24 +0000, Dimitri van Heesch wrote:

Which language was your class written in?

For C# code (.cs extension) doxygen treats ... the same as @code ... @Endcode, and your example will look fine.

For other languages is assumed to be a HTML command and is rendered as such.

On 2012-05-27 10:40:07 +0000, Markus Ewald wrote:

It's C++.

You can view the complete headers here: https://devel.nuclex.org/framework/browser/game/Nuclex.Game.Native/trunk/Include/Nuclex/Game/Timing

Microsoft's XML comment format is supported by their C++ compiler as well, it can be enabled in Project Settings - C/C++ - Output Files - Generate XML Documentation Files. I could use Sandcastle with the resulting XML files, but Doxygen generates much better output :)

Maybe you could decide how to process code tags based on whether or @code is used? I suspect anyone using the Microsoft style would expect the behavior documented on MSDN, though I've got no clue how popular those XML comments are for C++ developers.

On 2012-05-27 10:45:03 +0000, Dimitri van Heesch wrote:

I will treat a block inside a

or section as a XML command (so similar to @code), and a outside such section as a HTML command. I think that will give the expected results in most/all cases.

On 2012-06-10 09:41:47 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.1.1. 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.

On 2012-06-10 15:25:52 +0000, Markus Ewald wrote:

Thank you for the update! My block is now displayed with line breaks and is readable in the docs for the first time :)

The indentation is a bit distracting: http://i.imgur.com/Qmg95.png
But I believe Sandcastle behaves exactly the same.

It would be nice of the code block could be scanned for the least indented line and that then used as the starting column, but I don't know if this would be undesirable for the way other people use the @code / tag.

On 2012-06-23 12:13:59 +0000, Dimitri van Heesch wrote:

I'll make doxygen strip the leading indentation as well.

On 2012-07-15 11:47:31 +0000, Markus Ewald wrote:

Just tested Doxygen 1.8.1.2. The documentation now looks brilliant and the indentation is perfect: http://i.imgur.com/A0o3o.png

Thanks for all your effort!

@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