Skip to content

docs: full Doxygen API documentation for core data structures#414

Merged
wojdyr merged 15 commits into
project-gemmi:masterfrom
CV-GPhL:api-docs/core-structures
Apr 23, 2026
Merged

docs: full Doxygen API documentation for core data structures#414
wojdyr merged 15 commits into
project-gemmi:masterfrom
CV-GPhL:api-docs/core-structures

Conversation

@CV-GPhL
Copy link
Copy Markdown
Contributor

@CV-GPhL CV-GPhL commented Apr 22, 2026 •
edited
Loading

CI note: The test_sfcalc1/2/3 failures visible in this PR's checks are a pre-existing regression in upstream/master introduced by commit 0445d0c2 ("Add blob symmetry image test"), unrelated to the documentation changes here. The same tests fail on master's own CI. No C++ code was changed in this PR — only /// Doxygen comment blocks.

Summary

Adds complete, accurate full-Doxygen API documentation (every public class,
struct, enum, member, function — with @param/@return throughout) to the
eight core data structure headers:

Header Content
model.hpp Structure→Model→Chain→Residue→Atom hierarchy, enums, free functions
unitcell.hpp UnitCell, coordinate fractionalization/orthogonalization, NearestImage
symmetry.hpp SpaceGroup, GroupOps, Op (rational fraction encoding), ReciprocalAsu, enums
metadata.hpp Metadata, Entity, Connection, Assembly, NCS, Helix, Sheet, experiment info
elem.hpp El enum (atomic numbers), Element class
seqid.hpp SeqId (sequence number + insertion code), ResidueId, AtomAddress
resinfo.hpp ResidueKind enum, ResidueInfo, find_tabulated_residue()
small.hpp SmallStructure and Site for small molecules/inorganic crystals

Also expands docs/api.rst with doxygenfile:: entries for all eight headers.

Approach

  • Comments use /// triple-slash Doxygen style
  • Every entity was documented by reading the implementation first to ensure accuracy
  • Key accuracy verifications documented:
    • Op::rot/tran use rational fraction encoding with DEN=24
    • UnitCell angles stored in degrees; orthogonalization uses PDB convention (a along X)
    • NearestImage::dist_sq is squared distance in Ų
    • SeqId::icode = ' ' (space, not '\0') means no insertion code
    • Element::atomic_number() returns 1 for deuterium
  • PR Add documentation for include/gemmi headers #402 (Paul Emsley / pemsley) was audited; none of these 8 headers were touched by it

Literature references added

@par References Doxygen blocks added to cite primary sources in the rendered API docs:

Symbol Reference
vdw_radius() in elem.hpp Mantina et al. (2009) J. Phys. Chem. A 113, 5806 (doi); Bondi (1964) J. Phys. Chem. 68, 441 (doi)
rot_type() in symmetry.hpp Grosse-Kunstleve (1999) Acta Cryst. A55, 383 (doi)
nonzero_inversion_center() in symmetry.hpp ITA (2016) Vol. A, ch. 3.5 (doi)
calculate_matrix_B() in unitcell.hpp Busing & Levy (1967) Acta Cryst. 22, 457 (doi)
calculate_u_eq() in unitcell.hpp Fischer & Tillmanns (1988) Acta Cryst. C44, 775 (doi)

Depends on

This PR requires PR #413 (infrastructure) to be merged first.
See #413 for the Doxygen/Breathe build setup.

Part of series

PR Status Content
#413 Open Build infrastructure (Doxyfile, Breathe, readthedocs)
This PR Open Core data structures (8 headers)
PR 3 Planned CIF handling
PR 4 Planned Structure file I/O
PR 5–10 Planned Remaining headers

Verification

cd docs && make html   # api.html grows substantially with all 8 headers documented

Verified locally: doxygen 1.9.8, breathe 4.36.0, Sphinx 9.1.0.

C. Vonrhein and others added 12 commits April 22, 2026 14:07
docs: add Doxygen/Breathe infrastructure for C++ API reference
0c1d648 
Wires up Doxygen XML generation + Breathe Sphinx extension so that
C++ API documentation from header comments renders in the existing
Sphinx/readthedocs site at docs/api.rst.

- docs/Doxyfile: Doxygen config (XML-only output, internal headers excluded)
- docs/conf.py: runs Doxygen as subprocess, adds breathe extension
- docs/api.rst: stub C++ API reference page (expanded by subsequent PRs)
- docs/index.rst: replace external cxx-api link with internal api.rst
- docs/requirements.txt: add breathe >= 4.35
- .readthedocs.yaml: add apt_packages: [doxygen]
- .gitignore: exclude docs/_doxygen/ (generated)

Builds on prior work in project-gemmi#402 (Paul Emsley / pemsley).
Co-authored-by: C. Vonrhein / CV-GPhL
@claude
docs(model.hpp): add full Doxygen API documentation
2261737 
Add comprehensive Doxygen comments to the core data hierarchy header:
- File-level @file block explaining the Structure->Model->Chain->Residue->Atom hierarchy
- All enums: CoorFormat, CalcFlag, ResidueSs, ResidueStrandSense
- PdbReadOptions struct with field documentation
- Atom struct: all 13 members with clear descriptions
- Residue struct: detailed member and method documentation
- Chain struct: all residue access methods with use cases
- Model struct: search, modification, and query methods
- Structure class: complete documentation of 30+ members and methods
- Utility functions: is_same_conformer, add_distinct_altlocs, assign_residue_ss_from_file
- CRA/const_CRA/CraProxy types: bidirectional atom iteration framework
- All iterator policies and span types: ConstResidueSpan, ResidueSpan, ResidueGroup

Notable documentation:
- Clarified CoorFormat.Unknown vs CoorFormat.Detect semantics
- Explained CalcFlag.NoHydrogen == CalcFlag.NotSet (same numeric value)
- Documented altloc convention ('\0' = not set)
- Explained entity_type and entity_id relationship to mmCIF
- Detailed microheterogeneity and conformer handling
- Documented all major search/access methods

No warnings or errors in Doxygen build.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
docs(model.hpp): fix documentation gaps from spec review
8edaf7a
@claude
docs(unitcell.hpp): add full Doxygen API documentation
4bedabe 
Adds comprehensive Doxygen documentation to all public entities:

- File-level @file block with brief and detailed description
- Position and Fractional structs: purpose, fields, methods
- NearestImage struct: all fields explained, dist_sq units clarified
- UnitCell struct: 40+ public methods and members documented
  - Verified angles in degrees (via rad() conversion)
  - Verified PDB convention for orthogonalization (a-axis along X, a* along Z)
  - NearestImage::dist_sq units (squared distance in Angstroms^2)
- All helper functions: rot_as_mat33, tran_as_vec3
- Fractional/Cartesian transformation methods with conventions
- Distance/image finding methods with PBC and symmetry
- Reciprocal cell and reflection d-spacing calculations
- Metric tensor and special position detection

All comments use triple-slash (///) Doxygen style.
@param, @return, @brief tags provided for all non-trivial functions.
Build verified: Doxygen generates without errors.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@claude
docs(symmetry.hpp): add full Doxygen API documentation
019b32c 
Comprehensive documentation of all public API elements in symmetry.hpp:

- File-level @file block with overview of crystallographic structures
- Op struct: documented rot/tran encoding (rational fractions with DEN=24),
  real-space vs reciprocal-space operations, and all methods
- GroupOps struct: documented sym_ops/cen_ops separation, group operations,
  change-of-basis, and iteration
- Enums: CrystalSystem, PointGroup, Laue with @brief for each member
- SpaceGroup struct: documented all fields (number, ccp4, hm, ext, hall, etc.),
  reference settings, and accessor methods
- ReciprocalAsu struct: ASU boundary conditions, to_asu mapping, ISYM encoding
- Free functions: find/get space groups by name/number/ops, reciprocal ASU
- std::hash specialization for Op

All documentation follows Doxygen conventions:
- Triple-slash (///) for all public members
- @brief at every level (file, struct, enum, function, member)
- @param/@return/@throw for function signatures
- @tparam for template parameters (none present in this header)
- Inline descriptions (///<) for simple enumerators

Build verified: no new warnings or errors (3 pre-existing docutils warnings).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
docs(metadata.hpp): add full Doxygen API documentation
f2a7459
docs(elem.hpp): add full Doxygen API documentation
f281e30
docs(seqid.hpp): add full Doxygen API documentation
6ba6615
docs(resinfo.hpp): add full Doxygen API documentation
acde850
docs(small.hpp): add full Doxygen API documentation
2de6cfd
docs: fix documentation gaps from spec review (metadata, seqid, resinfo)
4143feb
docs(api.rst): add Core Data Structures section for PR 2
109a089
This was referenced Apr 22, 2026
Merged
Merged
Merged
Merged
@claude
fix(ci): guard doxygen call and breathe loading against missing doxygen
e75a546 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@CV-GPhL CV-GPhL force-pushed the api-docs/core-structures branch from 59655bc to e75a546 Compare April 22, 2026 21:16
CV-GPhL and others added 2 commits April 23, 2026 14:59
@CV-GPhL
docs: add @Par References citations to core-structures headers
ca3a9c8 
elem.hpp: Mantina/Truhlar (2009) and Bondi (1964) for vdW radii.
symmetry.hpp: RWGK (1999) for rotation type table;
  ITA (2016) for nonzero_inversion_center.
unitcell.hpp: Busing/Levy (1967) for B matrix convention;
  Fischer/Tillmanns (1988) for B_eq formula.

Co-authored-by: C. Vonrhein / CV-GPhL
@wojdyr
Merge branch 'master' into api-docs/core-structures
675f8e3
@wojdyr wojdyr merged commit cfc685f into project-gemmi:master Apr 23, 2026
1 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@CV-GPhL @wojdyr