Skip to content

keep cleaning source_cell#7684

Open
mohanchen wants to merge 3 commits into
deepmodeling:developfrom
mohanchen:v2-2026-07-24
Open

keep cleaning source_cell#7684
mohanchen wants to merge 3 commits into
deepmodeling:developfrom
mohanchen:v2-2026-07-24

Conversation

@mohanchen

Copy link
Copy Markdown
Collaborator

keep cleaning source_cell

@mohanchen
mohanchen requested a review from Critsium-xy July 24, 2026 06:27
@mohanchen mohanchen added Refactor Refactor ABACUS codes The Absolute Zero Reduce the "entropy" of the code to 0 labels Jul 24, 2026
@Critsium-xy

Critsium-xy commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

Two Doxygen-specific issues in the new comments that will affect the generated docs:

1. ///< used as a section header documents the wrong thing (and drops the text)

///< is a trailing comment — it documents the preceding declaration, not the line below it. In several places it's placed on its own line before a member as a section marker, e.g. in read_pp.h / pseudo.h:

///<PP_HEADER>
bool has_so = false;   ///< if .true. includes spin-orbit

Two problems here:

  • The ///<PP_HEADER> attaches backward (to whatever came before), so it does not label has_so.
  • Doxygen parses <PP_HEADER> as an unknown HTML tag and silently drops it (with a warning), so the section text is lost entirely.

Same pattern appears with ///<PP_INFO>, ///<PP_MESH>, ///<Dynamic arrays>, ///<VWR format>, ///<USPP>, ///<UPF201 format> (read_pp.h), and ///<K-point information> (parallel_kpoints.h).

Suggested fix — use a member group instead:

/// @name PP_HEADER
/// @{
bool has_so = false;   ///< if .true. includes spin-orbit
int  nv     = 0;       ///< UPF file version number
/// @}

or, if a group is overkill, just a plain /// line (no <, and avoid the angle brackets so it isn't read as HTML):

/// PP_HEADER
bool has_so = false;   ///< ...

2. Comma-listed @param won't render correctly

In symmetry.h (rhog_symmetry):

* @param nx, ny, nz grid dimensions
* @param fftnx, fftny, fftnz FFT grid dimensions

@param expects a single identifier; Doxygen will warn about undocumented params and mis-render these. Please split them:

* @param nx  grid dimension in x
* @param ny  grid dimension in y
* @param nz  grid dimension in z

(or use @param nx,ny,nz with no space after the commas, which Doxygen does accept as a shared description).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Refactor Refactor ABACUS codes The Absolute Zero Reduce the "entropy" of the code to 0

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants