Skip to content

Commit

Permalink
Value of first @copydoc could end up in the brief description.
Browse files Browse the repository at this point in the history 
Based on this observation: https://stackoverflow.com/q/70448684/784672
  • Loading branch information
@doxygen
doxygen committed Dec 23, 2021
1 parent 734121a commit ab74ff2
Showing 1 changed file with 6 additions and 1 deletion.
7 changes: 6 additions & 1 deletion src/commentscan.l
View file
Expand Up @@ -2838,7 +2838,12 @@ static bool handleCopyDetails(yyscan_t yyscanner,const QCString &, const StringV
static bool handleCopyDoc(yyscan_t yyscanner,const QCString &, const StringVector &)
{
struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
setOutput(yyscanner,OutputBrief);
if (yyextra->current->brief.isEmpty() && yyextra->current->doc.isEmpty())
{ // if we don't have a brief or detailed description yet,
// then the @copybrief should end up in the brief description.
// otherwise it will be copied inline (see bug691315 & bug700788)
setOutput(yyscanner,OutputBrief);
}
if (!yyextra->spaceBeforeCmd.isEmpty())
{
addOutput(yyscanner,yyextra->spaceBeforeCmd);
Expand Down

4 comments on commit ab74ff2

@albert-github
Copy link
Collaborator

@albert-github albert-github commented on ab74ff2 Dec 23, 2021 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this fix does work for the situation as given in the mentioned issue on stackoverflow (a bit smaller):

/// \file

/**
 * @brief OpenGL renderer rescale types
 */
enum class RescaleType {
    None, //!< No rescale
    Vertical, //!< Rescale vertically
};

/**
 * @brief
 *
 * With list<br>
 * - RescaleType::None @copydoc RescaleType::None
 * - RescaleType::Vertical @copydoc RescaleType::Vertical
 */
void    apply_rescale(RescaleType type);

but not for the situation without a list:

/// \file

/**
 * @brief OpenGL renderer rescale types
 */
enum class RescaleType {
    None, //!< No rescale
    Vertical, //!< Rescale vertically
};

/**
 * @brief
 *
 * No list<br>
 * RescaleType::None @copydoc RescaleType::None
 * RescaleType::Vertical @copydoc RescaleType::Vertical
 */
void    apply_rescale(RescaleType type);

which results in:
image

Note the extra white space.

Example: example.tar.gz

@albert-github
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another problem here occurs (and occurred before as well) when the splitting of \copydoc is done by hand in the components \copybrief and \copydetails like:

/// \file

/**
 * @brief OpenGL renderer rescale types
 */
enum class RescaleType {
    None, //!< No rescale
    Vertical, //!< Rescale vertically
};

/**
 * @brief
 *
 * No list<br>
 * RescaleType::None @copydoc RescaleType::None
 * RescaleType::Vertical @copydoc RescaleType::Vertical
 */
void    apply_rescale_doc(RescaleType type);
/**
 * @brief
 *
 * No list<br>
 * RescaleType::None @copybrief RescaleType::None @copydetails RescaleType::None
 * RescaleType::Vertical @copybrief RescaleType::Vertical @copydetails RescaleType::Vertical
 */
void    apply_rescale_split(RescaleType type);
/**
 * @brief
 *
 * No list<br>
 * RescaleType::None @copybrief RescaleType::None
 * RescaleType::Vertical @copybrief RescaleType::Vertical
 */
void    apply_rescale_brief(RescaleType type);

it gives some warnings like:

.../aa.h:28: warning: @copybrief or @copydoc target 'RescaleType::Vertical.' not found
.../aa.h:20: warning: @copybrief or @copydoc target 'RescaleType::None.' not found

and the output doesn't look nice either.

Example: example2.tar.gz

@doxygen
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've made some more fixes in 950c6ce
Note that since @copydoc is just @copybrief+@copydetails the position of @copydoc is important.

  • If it is inside the brief section of a comment block, the brief part of the pointed to documentation will end up in the brief section and the details will end up in the detailed section.
  • But if it is inside the detailed section both the brief and detailed part of the pointed to documentation will end up in the detailed section.

I think the guideline should be: use @copydoc if you want to duplicate the full comment and only want to optionally add some more details after the @copydoc, and use explicit @copybrief and @copydetails in other cases.

@albert-github
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a human it might all be clear what is intended, but it will be (nearly) impossible to get this tight in a program.

I agree with the guideline and I think the guideline:

I think the guideline should be: use @copydoc if you want to duplicate the full comment and only want to optionally add some more details after the @copydoc, and use explicit @copybrief and @copydetails in other cases.

should be mentioned in the documentation as well.
Furthermore with the @details command a user can also accomplish some more improvements.

Please sign in to comment.