Fix param names automatically by edgarcosta · Pull Request #2602 · flintlib/flint

edgarcosta · 2026-03-11T00:40:36Z

This is a follow-up to #1895 and the manual fixes in #2601. It adds dev/check_param_names.py, a tool that compares function parameter names across headers (.h), documentation (.rst), and source files (.c) to catch mismatches.

The tool treats the header as the source of truth and can auto-fix docs and sources to match. It currently finds 1758 functions with mismatches across 97 modules, totalling 3288 individual parameter name differences. Of these, 2573 can be auto-fixed; 21 are skipped due to local variable name collisions.

Example: `fmpzi` module

$ python3 dev/check_param_names.py --module fmpzi --check-src

======================================================================
Module: fmpzi
======================================================================

  --- header vs doc ---

  fmpzi_gcd:
    param 0: header has 'g', doc has 'res'
    header (src/fmpzi.h:176)
    doc (doc/source/fmpzi.rst:130)

  fmpzi_gcd_shortest:
    param 0: header has 'g', doc has 'res'
    header (src/fmpzi.h:175)
    doc (doc/source/fmpzi.rst:129)

  --- header vs source ---

  fmpzi_gcd:
    param 0: header has 'g', source has 'res'
    header (src/fmpzi.h:176)
    source (src/fmpzi/gcd.c:1)

  fmpzi_gcd_binary:
    param 1: header has 'x', source has 'X'
    param 2: header has 'y', source has 'Y'
    header (src/fmpzi.h:174)
    source (src/fmpzi/gcd_binary.c:53)

  ...

With --fix --dry-run, the tool shows what it would change and what it must skip:

$ python3 dev/check_param_names.py --module fmpzi --check-src --fix --dry-run

[dry-run] would fix fmpzi_gcd in src/fmpzi.h
  SKIP fmpzi_gcd_binary rename X->x in src/fmpzi/gcd_binary.c: collision with existing 'x'
  SKIP fmpzi_gcd_euclidean rename X->x in src/fmpzi/gcd_euclidean.c: collision with existing 'x'
  ...
[dry-run] would fix fmpzi_gcd_shortest in src/fmpzi.h
[dry-run] would fix fmpzi_gcd_shortest in src/fmpzi/gcd_shortest.c

======================================================================
Fixed: 3, Skipped: 0

Scope of auto-fixable changes per module

Module	Functions	Params	Module	Functions	Params
gr_poly	97	199	fmpq	22	57
arb_poly	95	189	ca	21	25
acb_poly	84	170	radix	21	79
arb	82	113	fmpz_mpoly_factor	20	25
fmpz	66	118	padic_poly	16	32
gr_mat	66	86	arb_fmpz_poly	15	28
nmod_poly	62	165	nmod_poly_mat	15	19
mag	61	85	ulong_extras	15	24
acb	59	94	fmpz_poly_mat	14	18
acb_hypgeom	52	108	nmod_mpoly_factor	14	21
fmpq_poly	51	145	fq_nmod	13	33
arb_hypgeom	50	99	qqbar	13	19
fmpz_poly	49	90	acb_dft	12	13
arf	47	60	acb_elliptic	12	14
fmpz_mpoly	46	91	bool_mat	12	25
fmpz_mod_poly	42	104	fmpz_mod_mpoly_factor	11	19
mpoly	32	42	nf_elem	11	22
ca_mat	30	49	arith	10	12
fmpz_mod_mpoly	29	43	fq_zech	10	20
fq_nmod_mpoly	28	62	+ 57 more modules
acb_mat	27	48	TOTAL	1758	3288
fmpq_mpoly	25	58
nmod_mpoly	23	50

How to proceed?

This tool is ready to auto-fix ~2500 parameter name mismatches across the codebase. However, given the scale, I'd like your input on how to proceed:

One big PR with all auto-fixes applied at once?
Batched PRs grouped by module family (e.g., all arb_*, all fmpz_*, etc.)?
Something else?

The remaining ~21 skipped cases (local variable collisions) would need separate manual fixes regardless of approach.

Usage

# Check all modules (header vs doc)
python3 dev/check_param_names.py

# Check specific module with source comparison
python3 dev/check_param_names.py --module fmpz --check-src

# Dry-run auto-fix
python3 dev/check_param_names.py --fix --check-src --dry-run

# Apply fixes
python3 dev/check_param_names.py --fix --check-src

# Run tests
python3 dev/test_check_param_names.py

Test plan

86 unit tests pass (python3 dev/test_check_param_names.py)

fredrik-johansson · 2026-03-11T11:36:36Z

Looks useful! With that said, automated renaming risks

creating inconsistencies with variable names used in surrounding text in the documentation and in code comments.
choosing the less descriptive name in some cases.

I'd rather run this on a few modules at a time, starting with modules that have not been updated recently, to be able to review everything manually.

Python tool (dev/check_param_names.py) that compares function parameter names across header declarations, RST documentation, and .c source definitions. Supports auto-fixing mismatches with --fix and --dry-run. Includes 86 unit tests (dev/test_check_param_names.py).

When two parameters have their names exchanged between header and source (e.g. header has val,len but source has len,val), the tool now prints a WARNING flagging a possible bug. This catches cases like _padic_poly_fprint_pretty where the header and source disagree on parameter order.

edgarcosta · 2026-03-11T22:34:51Z

Sounds good, I'll submit fixes a few modules at a time for manual review and to keep improving the script.

Here's the full list grouped by review effort, with the first batch already up in #2604:

Batch 1 (done, #2604)

arb_calc (1 fn, 2 params, last modified 2025-10-28)
ca_vec (7 fn, 9 params, last modified 2025-11-01)
fmpz_extras (1 fn, 3 params, last modified 2025-10-28)
padic_poly (16 fn, 32 params, last modified 2025-11-19)
thread_pool (1 fn, 2 params, last modified 2025-10-28)
Swap fixes in arb, gr_poly, nmod_mat

Batch 2: trivial modules (1-3 functions each, ~50 params total)

Batch 3: small modules (4-10 functions each, ~165 params total)

Batch 4: medium modules (11-25 functions each, ~530 params total)

Batch 5: large modules (26+ functions each, ~2470 params total)

edgarcosta · 2026-03-19T15:05:59Z

I might need to think a bit more about the next batches. They look horrendous to review. Maybe an interim approach is to have this merged and get CI to check the modules that we declare "done".

What do you think?

I would also take suggestions how to make this less painful to review. As we saw from the last one #2604, it took a couple of iterations between @fredrik-johansson and me to get it right, mostly the blame is on me.

fredrik-johansson · 2026-03-20T08:11:22Z

I might need to think a bit more about the next batches. They look horrendous to review. Maybe an interim approach is to have this merged and get CI to check the modules that we declare "done".

That's an option.

I would also take suggestions how to make this less painful to review. As we saw from the last one #2604, it took a couple of iterations between @fredrik-johansson and me to get it right, mostly the blame is on me.

If you want, we could schedule a session where I review the whole PR and we discuss the issues to fix in real time.

edgarcosta force-pushed the fix-param-names branch from d318f3d to a9e26d8 Compare March 11, 2026 14:35

edgarcosta mentioned this pull request Mar 11, 2026

First batch of doc <-> header <-> source alignment #2604

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix param names automatically#2602

Fix param names automatically#2602
edgarcosta wants to merge 2 commits intoflintlib:mainfrom
edgarcosta:fix-param-names

edgarcosta commented Mar 11, 2026

Uh oh!

fredrik-johansson commented Mar 11, 2026

Uh oh!

edgarcosta commented Mar 11, 2026

Uh oh!

edgarcosta commented Mar 19, 2026

Uh oh!

fredrik-johansson commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

edgarcosta commented Mar 11, 2026

Example: fmpzi module

Scope of auto-fixable changes per module

How to proceed?

Usage

Test plan

Uh oh!

fredrik-johansson commented Mar 11, 2026

Uh oh!

edgarcosta commented Mar 11, 2026

Batch 1 (done, #2604)

Batch 2: trivial modules (1-3 functions each, ~50 params total)

Batch 3: small modules (4-10 functions each, ~165 params total)

Batch 4: medium modules (11-25 functions each, ~530 params total)

Batch 5: large modules (26+ functions each, ~2470 params total)

Uh oh!

edgarcosta commented Mar 19, 2026

Uh oh!

fredrik-johansson commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Example: `fmpzi` module