Skip to content

DOC: Grouping shared documentation #225

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 1 commit into from
Mar 28, 2025
Merged

DOC: Grouping shared documentation #225

merged 1 commit into from
Mar 28, 2025

Conversation

albert-github
Copy link
Contributor

Written a small item about grouping shared documentation.

@github-actions github-actions bot added area:Appendices Issues affecting the Appendices part language:LaTeX Changes to LaTeX code type:BookStyle Changes to book style files type:Documentation Documentation improvement or change labels Mar 23, 2025
@albert-github
Copy link
Contributor Author

Documentation for InsightSoftwareConsortium/ITK#5262

jhlegarreta
jhlegarreta reviewed Mar 23, 2025
View reviewed changes
Copy link
Member

@jhlegarreta jhlegarreta left a comment

Choose a reason for hiding this comment

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

/** @ITKStartGrouping */ vs. /**@ITKEndGrouping*/ : why does the former need whitespaces before/after the alias?

SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex
@@ -4273,6 +4273,22 @@ \subsection{Documenting Data Members}
\code{Set\#\#name} method should also be documented following the above
guidelines.

Data members that should share the same documentation description should be embedded in
the Doxygen grouping commands by means of the comments \code{/** @ITKStartGrouping */}
Copy link
Member

Choose a reason for hiding this comment

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

by means of : using ?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@jhlegarreta Not sure if this is meant as correction or as a style / discussion item from your side?

Copy link
Member

Choose a reason for hiding this comment

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

Sounds more straightforward.

@albert-github
Copy link
Contributor Author

albert-github commented Mar 23, 2025 •
edited
Loading

/** @ITKStartGrouping */ vs. /**@ITKEndGrouping*/ : why does the former need whitespaces before/after the alias?

The whitespace is not relevant here, but I used the same comments as I used in the mentioned PR InsightSoftwareConsortium/ITK#5262

@jhlegarreta
Copy link
Member

The whitespace is not relevant her, but I used the same comments as I used in the mentioned PR InsightSoftwareConsortium/ITK#5262

If they are arbitrary, then please remove them.

@albert-github
Copy link
Contributor Author

I'd rather add them to the /**@ITKEndGrouping*/ for better readability.
Should the change also be done in the metioned PR?

@jhlegarreta
Copy link
Member

I'd rather add them to the /**@ITKEndGrouping*/ for better readability.

👍.

Should the change also be done in the metioned PR?

Yes, please. Thanks.

albert-github added a commit to albert-github/ITK that referenced this pull request Mar 24, 2025
@albert-github
DOC: fixing "unbalanced grouping commands" warnings
16b1e55 
Based on review in InsightSoftwareConsortium/ITKSoftwareGuide#225 (comment)
dzenanz
dzenanz approved these changes Mar 24, 2025
View reviewed changes
Copy link
Member

@dzenanz dzenanz left a comment

Choose a reason for hiding this comment

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

Looks great! To be squashed upon merging.

@dzenanz dzenanz mentioned this pull request Mar 24, 2025
Merged
2 tasks
@thewtex thewtex requested review from N-Dekker and hjmjohnson March 24, 2025 18:46
@albert-github @dzenanz
DOC: Grouping shared documentation
9d9f5c5 
Written a small item about grouping shared documentation.
@dzenanz dzenanz force-pushed the feature/bug_grouping branch from 787cb69 to 9d9f5c5 Compare March 25, 2025 13:25
@dzenanz dzenanz merged commit 5ea45e3 into InsightSoftwareConsortium:main Mar 28, 2025
3 checks passed
@albert-github albert-github deleted the feature/bug_grouping branch March 28, 2025 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jhlegarreta jhlegarreta jhlegarreta left review comments

@dzenanz dzenanz dzenanz approved these changes

@N-Dekker N-Dekker Awaiting requested review from N-Dekker

@hjmjohnson hjmjohnson Awaiting requested review from hjmjohnson

Assignees
No one assigned
Labels
area:Appendices Issues affecting the Appendices part language:LaTeX Changes to LaTeX code type:BookStyle Changes to book style files type:Documentation Documentation improvement or change
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@albert-github @jhlegarreta @dzenanz