docs: audit and clarify all function docstrings - #462
Merged
Conversation
- calculateMW: state the MW unit (Da) explicitly. - reportEnzymeUsage: remove the redundant repeated summary line, tighten the highCapUsage/topAbsUsage descriptions, document that topAbsUsage omits enzymes with no flux-carrying reactions, and correct the Returns section to describe the actual struct fields (it previously just said "table with summary information", but usageReport is a struct with two tables and a scalar).
… and tutorials Reviewed every top-level function's header docstring for clarity and accuracy. Removed redundant summaries that just restated the one-line header, dropped historical/regression narration and cross-implementation comparisons in favor of stating current behavior plainly, fixed several docstrings that no longer matched the code (wrong struct field names, wrong defaults, wrong thresholds, stale claims predating later changes), and clarified vague Parameters/Returns descriptions. Docstring/comment-only; no functional changes. Full unit test suite (46/46) passes unchanged.
Unit test results46 tests 46 ✅ 9s ⏱️ Results for commit 7dd3aad. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Full pass over every header docstring in
src/geckomat,test/, andtutorials/, following up on #459/#460/#461. Goal: a docstring should tella reader what the function produces and what its inputs do, without
narrating implementation history or repeating itself. Comment/docstring
only -- no functional changes, verified by a full 46/46 unit test pass.
Recurring patterns fixed across many files:
it (
findMetSmiles,findECInDB,runDLKcat,loadFluxData,getConcControlCoeffs,abc_max,findMaxValue,sensitivityTuning,sigmaFitter,truncateValues, and others).Returns/argument descriptions that no longer matched the code: wrongstruct field names in
kcatList(fuzzyKcatMatching,readDLKcatOutput,selectKcatValue), a vague "table"/"struct" return with no indication ofits actual columns/fields (
applyComplexData,applyCustomKcats,mergeKcats,mergeDLKcatAndFuzzyKcats,updateProtPool), an inaccuratethreshold (
applyCustomKcats: code uses>= 50%, not> 50%), and adocstring that predated the KEGG-fallback path added later in the same
function (
makeEcModel).current behavior:
loadBRENDAdata's "previous, single-aggregatebehaviour" note,
relaxProteomicsGreedy's porting/attribution paragraph,updateProtPool's "Obsolete since / Before GECKO 3.2.0" framing (nowstates when the function errors instead),
pfbaEnzymes'sgeckopy-attribution and implementation-detail asides, and 32 of the
46 tests in
geckoCoreFunctionTests.mwhose docstrings were empty(
%full) or long bug-regression narratives (RAVEN/PR/issue references,"used to...", "cross-verified against geckopy" framing) -- rewritten to
state the scenario each test verifies.
changeMediawas missing two documentedparameters and mis-described two others (
anoxisn't boolean,fluxisn't a cell array);
scaleBioMass_GECKOmis-described its own defaultbehavior;
light_ecModel/protocol.m's header wrongly described thefull yeast-GEM model instead of the light Human-GEM one it actually
covers.
Functions found with no docstring at all (mostly small local helpers, plus
ModelAdapter/ModelAdapterManager's methods andGECKOInstaller'sstatic methods) were left untouched rather than given an invented one --
out of scope for a wording/accuracy pass.