Skip to content

Fix doc comment pre-processing in erfa_generator#238

Merged
avalentino merged 1 commit intoliberfa:mainfrom
eerovaher:docstring-asterisks
May 1, 2026
Merged

Fix doc comment pre-processing in erfa_generator#238
avalentino merged 1 commit intoliberfa:mainfrom
eerovaher:docstring-asterisks

Conversation

@eerovaher
Copy link
Copy Markdown
Contributor

There are small peculiarities in the eraLdn() and eraAticqn() doc comments which are removed in a pre-processing step. However, in current main the pre-processing is not specific enough, so it also makes unintentional changes to doc comments of several other functions. As a result the docstrings of the Python wrappers that are supposed to include a copy of the C doc comments erroneously document most pointers as their targets instead. Additionally, the affected lines tend to become misaligned. This PR makes the pre-processing much more specific, which fixes the generated Python docstrings.

The difference between erfa/core.py generated by current main and this PR is

821c821
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
1086c1086
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
1223c1223
<            astrom eraASTROM        star-independent astrometry parameters:
---
>            astrom eraASTROM*  star-independent astrometry parameters:
1240c1240
<            eo     double           equation of the origins (ERA-GST, radians)
---
>            eo     double*     equation of the origins (ERA-GST, radians)
1382c1382
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
1603c1603
<            eo     double          equation of the origins (ERA-GST, radians)
---
>            eo     double*    equation of the origins (ERA-GST, radians)
1781c1781
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
1926c1926
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
2054c2054
<            astrom  eraASTROM        star-independent astrometry parameters:
---
>            astrom  eraASTROM*  star-independent astrometry parameters:
2073c2073
<            astrom  eraASTROM        star-independent astrometry parameters:
---
>            astrom  eraASTROM*  star-independent astrometry parameters:
2172c2172
<            astrom  eraASTROM        star-independent astrometry parameters:
---
>            astrom  eraASTROM*  star-independent astrometry parameters:
2191c2191
<            astrom  eraASTROM        star-independent astrometry parameters:
---
>            astrom  eraASTROM*  star-independent astrometry parameters:
2324c2324
<            astrom eraASTROM        star-independent astrometry parameters:
---
>            astrom eraASTROM*  star-independent astrometry parameters:
2485c2485
<            astrom eraASTROM        star-independent astrometry parameters:
---
>            astrom eraASTROM*  star-independent astrometry parameters:
2678c2678
<            ra,da  double        ICRS astrometric RA,Dec (radians)
---
>            ra,da  double*  ICRS astrometric RA,Dec (radians)
2796c2796
<            ra,da  double          ICRS astrometric RA,Dec (radians)
---
>            ra,da  double*    ICRS astrometric RA,Dec (radians)
3086c3086
<            astrom eraASTROM         star-independent astrometry parameters:
---
>            astrom eraASTROM*   star-independent astrometry parameters:
3342,3347c3342,3347
<            aob    double        observed azimuth (radians: N=0,E=90)
<            zob    double        observed zenith distance (radians)
<            hob    double        observed hour angle (radians)
<            dob    double        observed declination (radians)
<            rob    double        observed right ascension (CIO-based, radians)
<            eo     double        equation of the origins (ERA-GST, radians)
---
>            aob    double*  observed azimuth (radians: N=0,E=90)
>            zob    double*  observed zenith distance (radians)
>            hob    double*  observed hour angle (radians)
>            dob    double*  observed declination (radians)
>            rob    double*  observed right ascension (CIO-based, radians)
>            eo     double*  equation of the origins (ERA-GST, radians)
3706c3706
<            astrom eraASTROM        star-independent astrometry parameters:
---
>            astrom eraASTROM*  star-independent astrometry parameters:
3859,3863c3859,3863
<            aob    double        observed azimuth (radians: N=0,E=90)
<            zob    double        observed zenith distance (radians)
<            hob    double        observed hour angle (radians)
<            dob    double        observed declination (radians)
<            rob    double        observed right ascension (CIO-based, radians)
---
>            aob    double*  observed azimuth (radians: N=0,E=90)
>            zob    double*  observed zenith distance (radians)
>            hob    double*  observed hour angle (radians)
>            dob    double*  observed declination (radians)
>            rob    double*  observed right ascension (CIO-based, radians)
4034,4038c4034,4038
<            aob    double          observed azimuth (radians: N=0,E=90)
<            zob    double          observed zenith distance (radians)
<            hob    double          observed hour angle (radians)
<            dob    double          observed declination (radians)
<            rob    double          observed right ascension (CIO-based, radians)
---
>            aob    double*    observed azimuth (radians: N=0,E=90)
>            zob    double*    observed zenith distance (radians)
>            hob    double*    observed hour angle (radians)
>            dob    double*    observed declination (radians)
>            rob    double*    observed right ascension (CIO-based, radians)
4362,4363c4362,4363
<            ri     double        CIRS right ascension (CIO-based, radians)
<            di     double        CIRS declination (radians)
---
>            ri     double*  CIRS right ascension (CIO-based, radians)
>            di     double*  CIRS declination (radians)
4545,4546c4545,4546
<            ri     double          CIRS right ascension (CIO-based, radians)
<            di     double          CIRS declination (radians)
---
>            ri     double*    CIRS right ascension (CIO-based, radians)
>            di     double*    CIRS declination (radians)
5225,5226c5225,5226
<           refa   double         tan Z coefficient (radians)
<           refb   double         tan^3 Z coefficient (radians)
---
>           refa   double*   tan Z coefficient (radians)
>           refb   double*   tan^3 Z coefficient (radians)
5761c5761
<                      C instead of Fortran.
---
>              *  C instead of Fortran.
5763c5763
<                      The date is supplied in two parts.
---
>              *  The date is supplied in two parts.
5765c5765
<                      The result is returned only in equatorial Cartesian form;
---
>              *  The result is returned only in equatorial Cartesian form;
5769c5769
<                      The result is in the J2000.0 equatorial frame, not ecliptic.
---
>              *  The result is in the J2000.0 equatorial frame, not ecliptic.
5771c5771
<                      More is done in-line: there are fewer calls to subroutines.
---
>              *  More is done in-line: there are fewer calls to subroutines.
5773c5773
<                      Different error/warning status values are used.
---
>              *  Different error/warning status values are used.
5775c5775
<                      A different Kepler's-equation-solver is used (avoiding
---
>              *  A different Kepler's-equation-solver is used (avoiding
5778c5778
<                      Polynomials in t are nested to minimize rounding errors.
---
>              *  Polynomials in t are nested to minimize rounding errors.
5780c5780
<                      Explicit double constants are used to avoid mixed-mode
---
>              *  Explicit double constants are used to avoid mixed-mode
19137c19137
<            sign    char         '+' or '-'
---
>            sign    char*   '+' or '-'
19219c19219
<            sign    char         '+' or '-'
---
>            sign    char*   '+' or '-'
19446c19446
<            sign    char         '+' or '-'
---
>            sign    char*   '+' or '-'

There are small peculiarities in the `eraLdn()` and `eraAticqn()` doc
comments which are removed in a pre-processing step. However, the
pre-processing has not been specific enough, so it has also made
unintentional changes to doc comments of several other functions. As a
result the docstrings of the Python wrappers that are supposed to
include a copy of the C doc comments have been erroneously documenting
most pointers as their targets instead. Additionally, the affected lines
tended to become misaligned. Now the pre-processing is much more
specific, which fixes the Python docstrings.
Comment thread erfa_generator.py
def __init__(self, doc):
self.doc = doc.replace("**", " ").replace("/*\n", "").replace("*/", "")
self.doc = self.doc.replace("/*+\n", "") # accommodate eraLdn
self.doc = self.doc.replace("* ", " " * 2) # accommodate eraAticqn
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This line is the main culprit. It replaces the substring "* " with " " anywhere within the doc comment of any function, but should only replace the beginnings of two lines in the eraAticqn() doc comment.

@avalentino avalentino merged commit 3cd0e99 into liberfa:main May 1, 2026
28 checks passed
@eerovaher eerovaher deleted the docstring-asterisks branch May 1, 2026 20:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants