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

Line breaks are not copied/displayed properly when using @copydoc. (Origin: bugzilla #691315) #5023

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.3 on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

On 2013-01-07 20:58:29 +0000, Adam Shapiro wrote:

When @copydoc or @copydetails are used, any (non-explicit) line breaks in the details section seem to get stripped away in the output. The documentation for the source function looks correct, but the documentation for any functions that copy the source's details are printed as one big paragraph.

This bug exists in 1.8.0 (Cygwin build) and 1.8.3 (native Windows build). I've attached a test header that highlights the issue.

On 2013-01-07 20:59:02 +0000, Adam Shapiro wrote:

Created attachment 232941
Test cases.

On 2013-01-13 21:09:08 +0000, Dimitri van Heesch wrote:

Confirmed. Should be fixed in the next subversion update.

On 2013-01-13 21:10:09 +0000, Dimitri van Heesch wrote:

*** Bug 682550 has been marked as a duplicate of this bug. ***

On 2013-01-20 13:34:54 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.3.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 2013-01-22 13:40:05 +0000, Adam Shapiro wrote:

The line breaks are now being copied properly, but two new issues have shown up:

First, additional parameters for functions using @copydoc do not get processed and instead produce a "parameter not documented" warning. This occurs with the detailsButMore() function in the attached example.

Second, if a @copydoc is split into separate @copybrief and @copydetails statements, only the first one listed is processed. This arose from trying to debug the first error above. Add the following functions to the example code to highlight:

/**
 * @copybrief A::func()
 *
 * @copydetails A::func()
 *
 * @param b Another parameter.
 */
int copybriefOnly(int a, double b);

/**
 * @copydetails A::func()
 *
 * @copybrief A::func()
 *
 * @param b Another parameter.
 */
int copydetailsOnly(int a, double b);

I don't know if these issues are related to the original bug, so I'm not sure if I should create new bug reports, or if reopening this bug is appropriate.

On 2013-05-23 17:59:50 +0000, Kyle wrote:

I actually preferred the old behavior, at least for @copybrief, which allowed something like the following:

-# Item 1: \copybrief item1
-# Item 2: \copybrief item2
-# Item 3: \copybrief item3

The new behavior causes paragraph breaks between the list items, which causes a very choppy appearance and constant restarting of each list number at 1. Would it be possible to have copybrief have a flag to not create a new paragraph? Or have copybrief maintain the old behavior?

(I actually don't like the brief descriptions to be in their own paragraph--seeing as they are only one sentence it looks odd to have a standalone sentence as a paragraph, but that's another issue altogether)

On 2013-05-23 18:16:20 +0000, Kyle wrote:

(In reply to comment # 6)

FYI: In further poking around, I've noted this is also requested in https://bugzilla.gnome.org/show_bug.cgi?id=700788

On 2013-05-24 09:09:48 +0000, Fabrizio Da Ros wrote:

I agree with Kyle, I extensively used the same pattern
-# Item 1: \copybrief item1
-# Item 2: \copybrief item2
-# Item 3: \copybrief item3
in many projects.

I have the same opinion: since brief is a single line description it makes sense to avoid creation of a stand alone paragraph.

The @copybrief is very useful to create lists like what the modules page does. Or to mention it in the middle of a text to quickly recall the meaning of an item.

To summarize, preferred @copybrief behaviour as version 1.8.3

On 2013-05-26 19:12:53 +0000, Dimitri van Heesch wrote:

I've just committed a patch to the GIT repository to address to \copy* related issues.

I've now used a separate pass to resolve the \copy* commands before they are passed to the comment parser. This means that \copy* commands now really act as "copy&paste" operations, as requested by Adam, Kyle and Fabrizio.

Please try the latest snapshot from GitHub if you want to try for yourself, and let me know if you see any problems.

On 2013-05-26 19:14:37 +0000, Dimitri van Heesch wrote:

*** Bug 700788 has been marked as a duplicate of this bug. ***

On 2013-05-28 07:34:56 +0000, Fabrizio Da Ros wrote:

Created attachment 245431
copybrief, copydetails HTML rendering comparison 1761 183 184

Contains source code and Doxygen output

On 2013-05-28 07:36:26 +0000, Fabrizio Da Ros wrote:

Created attachment 245432
copybrief, copydetails HTML rendering comparison 1761 183 184

On 2013-05-28 07:37:55 +0000, Fabrizio Da Ros wrote:

I mulled over the \copy* feature.
I would like to share my point of view.

  1. \copybrief
    The \copybrief should work as "copy&paste", without any surrounding

    . The v1.8.3 was implementing it. To have the paragraph separation, if required, one can add new-lines around a \copybrief command.
    v1.8.3 is acting as described. The rendering of \copybrief in v1.8.3 is simply perfect in my opinion. Without any switch it is possible to properly obtain both behaviours.
    Unfortunately I'm not able to test the latest snapshot

  2. \copydetails
    I think this is a different story. Since we are talking about details, it's natural to imagine some verbose text with paragraph separation in between. Even though it could be a single line, it's nature is structured.
    I rather expect to see the paragraph original structure when \copydeatils is used, as opposite of a \copybrief. The v1.7.6.1 was doing agreat job with it. Output of v1.8.4 looks similar to v1.7.6.1 but is not "nesting" text. I personally prefer output of 1.7.6.1.

To summarize:
\copybrief as v1.8.3 - no paragraph
\copydetails as v1.7.6.1 - with paragraphs (and nesting?)

I discovered that a single line text in a page is not treated as brief description (see test2 in the attached example).

Attached you can find source code and HTML rendering result for v1.7.6.1, v1.8.3 and v1.8.4

What do you think?

On 2013-06-13 15:43:40 +0000, Kyle wrote:

I tend to agree with Fabrizio--\copydetails should retain formatting. I don't seem to be able to build the Windows version from git with my version of VS (I've got 2010, something about the project auto-update failed).

I'd be happy to try it out if somebody builds a copy though. Otherwise I'll poke more at getting it to build as I can find time...

On 2013-06-13 17:13:37 +0000, Kevin McBride wrote:

Kyle,

I have filed a bug report about the windows build files not being able to auto-update and build doxygen. If you figure out what changes need to be made to get VS 2010 to build doxygen, please post them to bug 697511.

On 2013-08-23 15:04:13 +0000, Dimitri van Heesch wrote:

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

@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