Skip to content

docs: four KPI functions in philanthropy.metrics._scoring document neither Parameters nor Returns #60

Description

@shivamlalakiya

Summary

All four functions in philanthropy/metrics/_scoring.pydonor_retention_rate,
donor_acquisition_cost, cost_per_dollar_raised, fundraising_roi — have a
prose summary and a short explanatory paragraph, but none has a formal
Parameters or Returns section. The API reference is generated by
mkdocstrings from a bare ::: philanthropy.metrics directive, so each of
these four renders with its signature and the prose, but the arguments and
return value are not itemised the way every other metric in the package
documents them (see gift_concentration_gini or top_donor_share in
philanthropy/metrics/_concentration.py for the shape to copy).

This is a good first issue: no logic changes, and the prose already explains
the behaviour — the work is reformatting it into NumPy sections.

Where

File Locate with
philanthropy/metrics/_scoring.py grep -n "^def " philanthropy/metrics/_scoring.py

What to change

NumPy format (mkdocs.yml sets docstring_style: numpy). For each of the four
functions, add:

  • Parameters — every keyword-only argument, one line each.
  • Returns — the value and, where the function has one, the np.inf sentinel
    case already described in the existing prose (e.g. "np.inf when
    new_donors_acquired is 0").

Keep the existing prose as the summary line(s) above the new sections; don't
delete the explanatory context, just add the missing structure around it.

Tests to add or extend

None — doc-only change, no new branch to cover.

Done when

python -c "
import inspect, sys, philanthropy.metrics as M
missing = [
    n for n in ('donor_retention_rate', 'donor_acquisition_cost',
                'cost_per_dollar_raised', 'fundraising_roi')
    if 'Parameters' not in (getattr(M, n).__doc__ or '')
    or 'Returns' not in (getattr(M, n).__doc__ or '')
]
print('MISSING:', missing or 'none'); sys.exit(1 if missing else 0)
" && echo OK
python -m pytest philanthropy --doctest-modules -q --no-cov

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationeasySmall, well-scoped, single-file changegood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions