Fix malformed and missing docstrings in the API reference

Start by reviewing the public functions listed in ipmag, pmag, pmagplotlib, and rockmag, then reproduce the audit with inspect.getdoc and sphinx.ext.napoleon as described. Apply the listed formatting fixes and determine appropriate content or visibility for undocumented helpers. Confirm the API reference renders correctly, keeping in mind that the docs workflow installs the latest PyPI release.

This issue replaces #673 with a narrower, checkable list.

#673 proposed converting all docstrings to Google style because our NumPy-style docstrings were rendering poorly in the API reference. That wholesale conversion is not needed. The docs build uses sphinx.ext.napoleon, which parses both styles, and a well-formed NumPy-style docstring (most of pmag and rockmag) renders with the same Parameters/Returns field lists as a Google-style one (most of ipmag). Either style is fine as long as it is well formed.

What remains is a set of specific functions whose docstrings are malformed, incomplete, or missing. The list below comes from running napoleon over every public function in the four modules included in the API reference (ipmag, pmag, pmagplotlib, rockmag) on current master, and cross-checking against the rendered page.

Result	Count
Renders properly (either style)	347
Has arguments but no Parameters section	68
No docstring, so absent from the API reference	40
Parameters/Returns fields run into the summary paragraph	18
Section headers that napoleon does not parse	14
Whole docstring rendered as a block quote	3

Mechanical fixes (35 functions)

These need no new content, only formatting changes.

Fields run into the summary paragraph (18)

There is no blank line between the summary and the Parameters header, so the generated :param: lines are absorbed into the summary paragraph and show up as raw text. Fix: add a blank line before Parameters.

• ipmag: validate_magic, zeq_magic
• pmagplotlib: draw_figs, gaussfunc, plot_cdf, plot_circ, plot_ell, plot_eq, plot_eq_cont, plot_eq_sym, plot_init, plot_net, plot_qq_norm, plot_qq_unf, plot_square, plot_strat
• rockmag: SD_MD_mixture, SP_SD_mixture

Section headers that napoleon does not parse (14)

• Google-style Parameters: header whose entries are not indented beneath it, so the section is left as plain text. Fix: indent the entries. ipmag.kent_distribution_95, ipmag.rand_correlation_prob, ipmag.reversal_test_MM1990, pmagplotlib.msp_magic, pmagplotlib.plot_ts, pmagplotlib.plot_map
• Singular Parameter:. ipmag.inc_from_lat, ipmag.lat_from_inc
• Returns : with a space before the colon. ipmag.criteria_extract
• Bare Parameters / Returns with neither an underline nor a colon. pmag.b_vdm
• Input / Output headers. pmagplotlib.plot_hys, pmagplotlib.plot_hdd
• Required Parameters / Optional Parameters headers. ipmag.smooth
• Command-line style NAME / DESCRIPTION / Keywords: layout. ipmag.zeq

Whole docstring rendered as a block quote (3)

• pmag.dms2dd and pmag.convert_ages: a line in the Examples section starts at column 0, so the docstring is never dedented and all of it renders as an indented block quote. Fix: indent those lines to match the rest of the docstring.
• pmagplotlib.delticks: the summary line is indented one space more than the rest, and there is no blank line before Parameters.

Needs content

Has arguments but no Parameters section (68)

Many of these are legacy helpers. For some, the better outcome may be a leading underscore or removal rather than documentation.

• ipmag (10): MADcrit_95_filter, ani_depthplot2, aniso_magic_nb, calculate_aniso_parameters, orientation_magic, plate_rate_mc, plot_di_mean_bingham, shoot, specimens_results_magic, upload_magic2
• pmag (40): Dir_anis_corr, PintPars, add_flag, adjust_ages, adjust_all_to_360, adjust_to_360, adjust_val_to_360, binglookup_old, cdfout, cleanup, doaniscorr, domagicmag, find_samp_rec, first_up, get_EOL, get_age, get_specs, get_ts, getkeys, grade, initialize_acceptance_criteria, linreg, magic_read_dict, measurements_methods, measurements_methods3, merge_recs_headers, parse_site, pseudosample, putout, read_criteria_from_file, scoreit, set_priorities, sortmwarai, sortshaw, vclose, vocab_convert, vspec, vspec_magic, vspec_magic3, watsonsV
• pmagplotlib (18): add_borders, k_s, plot3d_init, plot_b, plot_bcr, plot_conf, plot_dir, plot_hpars, plot_imag, plot_ltc, plot_site, plot_slnp, plot_xbt, plot_xft, plot_xtb, plot_xtf, plot_xy, qsnorm

No docstring (40)

automodule is run without :undoc-members:, so these do not appear in the API reference at all.

• ipmag (4): aniso_magic_old, plot_aniso, read_core_csv_file, upload_magic3
• pmag (22): ParseMeasFile, ParseSiteFile, ReorderSamples, average_int, check_F, convert_meas_2_to_3, cooling_rate, default_criteria, get_attr, get_curve, get_flag_arg_from_sys, get_list, getfield, getsampVDM, getsampVGP, lnpbykey, main, mark_samp, mw_measurements_methods, remove_files, sortbykeys, write_criteria_to_file
• pmagplotlib (14): clearFIG, click, plot_anis, plot_com, plot_di, plot_di_sym, plot_ei, plot_tds, plot_trm, plot_v2s, save_or_quit, show, show_fig, vertical_plot_init

Note on when fixes become visible

The PmagPy-docs build workflow runs pip install pmagpy, so the published API reference reflects the latest PyPI release, not master. Docstring fixes will only show up on the site after a release, unless the workflow is changed to install from GitHub.

Reproducing the audit

For each public function, pass inspect.getdoc(f) through sphinx.ext.napoleon.docstring.GoogleDocstring and then NumpyDocstring (both enabled, as in the docs config) and inspect the resulting reST: leading whitespace on the first line indicates a dedent failure, a :param: line directly following summary text indicates a missing blank line, and any surviving Parameters/Returns/Input/Output header line was not parsed.

Generated by Claude Fable 5.1 (Claude Code) on behalf of NSH