Correct the documentation against what the code actually does - #27
Merged
Conversation
CONTRIBUTING still described a Unix-only tool with 21 tests, five modules, no side-effect capture and 15-20x recording overhead. The README's sample output predated the record shape that carries argument mutation and file writes, and both files documented include/exclude patterns in a form that silently matches nothing when the named target is a module rather than a package.
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.
An audit of every factual claim in the README, CONTRIBUTING, module docstrings and
--help, checked against the code and by running each documented command in throwaway repos. Seventeen were wrong.The one that matters most is a real trap I shipped: the documented pattern
--include "mypkg.core.*"matches nothing. Targets aremodule:Qualname, so the dot never matchesmypkg.core:parse, and a user following the README would silently record zero functions. Corrected tomypkg.core*, with a sentence naming the trap.CONTRIBUTING.mdhad missed the last day entirely: it claimed 21 tests, five source files, that file writes were invisible, that numpy and datetimes were open questions, 15-20x overhead, and that Windows was unsupported. All now match reality.The README also promised that skipped callables are named — only the count is printed — and still solicited work on datetime/UUID comparators that #12 settled by rejecting.
Flagged for you rather than guessed at, because nothing in the repo backs them: the header example numbers (
505 callables / 18402 inputs / 408 functions, where 18402 contradicts the measured table's 184,592), the measured results table itself, and the~8xfigure. Also noted:_print_reporthas no pluralisation, so it prints "1 functions" — left alone rather than enshrined in the docs.