DOC: Fix unbalanced grouping commands Doxygen warnings

[jhlegarreta]

Fix unbalanced grouping commands Doxygen warnings.

Fixes:

Modules/Core/Common/include/itkAutoPointer.h:261: warning: unbalanced grouping commands

warnings across classes.

The warning is raised when the
Utilities/Doxygen/itkdoxygen.pl

Doxygen Perl script processes the files at issue and starts a /**@{ block that gets interrupted by an unexpected symbol (e.g. a brace) without being previously closed with the corresponding /**@}*/ ending token.

Raised for example in:
https://open.cdash.org/viewBuildError.php?type=1&buildid=8344134

PR Checklist

• No API changes were made (or the changes have been approved)
• No major design changes were made (or the changes have been approved)

[jhlegarreta]

I checked the /**@{ /**@}*/ blocks for every file manually following #3654 (comment).

However, clang-format already warned me locally that it did not like the changes: it does not like changes in 61 files out of 79.

The pattern that we require to solve the Doxygen issues (that clang-format dislikes) looks to be "we require a blank line before closing the class with a };", as if we were to fulfill the condition in this comment:

ITK/Utilities/Doxygen/itkgroup.pl

Line 2 in 047fa69

# at next empty line add a //@}

@hjmjohnson @thewtex @dzenanz any suggestion on how we could work around this without having to recur to turning it on/off on each of these lines?

The other hypothesis is that the variable values in this condition

ITK/Utilities/Doxygen/itkgroup.pl

Line 68 in 047fa69

if($endparencount > 1 && ($semicount > 1 || $endbracecount > 1))

or the condition itself should be modified. Maybe the "//@}\n\n" ending block should be inserted at buffer_lines - 1 if we cannot work around the clang-format issue, and if that is possible.

Another possibility would be to submit only the changes that make clang-format happy, and increasingly add the rest on a case-by-case in case the required blank line can be introduced at some place other than the one where I introduced it.

[dzenanz]

It feels like we should update clang format style to allow the changes proposed here. I am not sure whether that can accomplish it.

[dzenanz]

I am running the build script with doxygen updated to 1.9.5, so we don't have to wait until tomorrow to see the updated output.

[jhlegarreta]

It feels like we should update clang format style to allow the changes proposed here. I am not sure whether that can accomplish it.

Looks like there may be a way:
https://stackoverflow.com/questions/33547172/clang-format-empty-line-between-end-of-class-declaration-and-closing-of-a-names
https://stackoverflow.com/questions/70732683/how-to-add-blank-lines-between-definitions

[dzenanz]

The second suggestion would require us to move to a newer clang-format (14 or later). We are currently at 8.0.0. Moving to a newer one shouldn't be a big change. The first suggestion looks like it would work now. Can you try it?

[dzenanz]

Doxygen 1.9.5 produces 100+ new warnings of style: Generating docDocumentation/Doxygen/NeighborhoodIterators.dox:96: warning: Unexpected token TK_HTMLTAG found as part of a title section. All warnings here. @jhlegarreta should we keep this version?

[jhlegarreta]

Doxygen 1.9.5 produces 100+ new warnings of style: Generating docDocumentation/Doxygen/NeighborhoodIterators.dox:96: warning: Unexpected token TK_HTMLTAG found as part of a title section. All warnings here. @jhlegarreta should we keep this version?

😓 I would keep the old version for now then. I would upgrade to the newer version once we have managed to fix the current warnings (which are still present in the new version).

[dzenanz]

I just reverted doxygen to 1.8.16.

[jhlegarreta]

The first suggestion looks like it would work now. Can you try it?

Looks like our clang-format options prevent it from working as described in the thread: https://github.com/InsightSoftwareConsortium/ITK/actions/runs/3727206860/jobs/6321140027#step:4:86

@hjmjohnson Do you happen to know the clang-format option that should do the work for our current version?

[dzenanz]

Adding end of class comment does trigger the described workaround:

  /** Sets the value of the image buffer at the current index value to the
   * specified value.  */
  void
  SetPixelValue(InternalPixelType * const imageBufferPointer, const PixelType & pixelValue) const noexcept
  {
    m_NeighborhoodAccessor.Set(imageBufferPointer + m_PixelIndexValue, pixelValue);
  }

}; // end of class

This is an excerpt from ITK\Modules\Core\Common\include\itkBufferedImageNeighborhoodPixelAccessPolicy.h, near the end.

[jhlegarreta]

#3805 (comment) OK, I was thinking about the namespace ending. I can do this, but I do not think we are willing to have this as a long-term solution.

@thewtex @blowekamp @hjmjohnson any thoughts?

[thewtex]

Another approach could replace itkdoxygen.pl with a Python script 🐍

[jhlegarreta]

Another approach could replace itkdoxygen.pl with a Python script 🐍

The problem is rather clang-format disliking the insertion of a blank line before the end of class closing bracket line without the latter having an inline comment.

[thewtex]

The problem is rather clang-format disliking the insertion of a blank line

Can we remove the insertion of the blank line in the Python script migration?

[jhlegarreta]

Can we remove the insertion of the blank line in the Python script migration?

It should rather be introduced: clang-format dislikes it and it keeps trying to remove it.

I do not have the bandwidth to translate the script into Python.

Alternatives:

• If you feel like modifying the Perl script to add such a blank line and have this tested, please go ahead ▶️.
• If you feel like to translating the script to Python and introducing the blank line, please go ahead ▶️.
• Otherwise, pinging @hjmjohnson to see if he can allow the blank like without changing the script.

[jhlegarreta]

Do you think the below approach plugged right after

ITK/Utilities/Doxygen/itkgroup.pl

Line 67 in 23da3df

}

can be made to work?

if($line =~ /\};/ )
{
  // Take the current buffer $buffer (assuming it includes the current line `};` as well) and add a blank line
  // immediately before `};` (if the current buffer does not include the current line, then include it right after
  // the buffer end)

  (doTheAboveStuff)

  // (I think we do not care that much if }; is not the end of the class definition (i.e. even if a lot of blank lines
  // are inserted) as this is only to produce proper Doxygen code)

  (save the $buffer)
}

so that we can get the result in #3805 (comment) without needing to add // end of class and thus bypass clang's unhappyness about adding a blank line? Or maybe there is another way to achieve it

@thewtex @tbirdso maybe one of you is skilled at Perl to give that a try? Thanks.

[dzenanz]

I still think that moving to latest stable clang-format (currently 15.0.7) is the best solution.

[jhlegarreta]

I still think that moving to latest stable clang-format (currently 15.0.7) is the best solution.

Would that fix the issue here ? Isn't the config itself, rather than the clang-format version, what might help ?

[dzenanz]

The current version ignores (does not support) the config setting we need. As per this SO answer, we need SeparateDefinitionBlocks, which was introduced with clang 14. So we need version 14+.

We already have MaxEmptyLinesToKeep: 2 in our config, and that is not enough.

[jhlegarreta]

#3805 (comment) OK, then +100 for upgrading. @hjmjohnson ?

[hjmjohnson]

@jhlegarreta I trust the judgment of those who have invested time into this PR. I will not have time to review it carefully.

[jhlegarreta]

Cross-referencing InsightSoftwareConsortium/ITKClangFormatLinterAction#3.