Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] Add interrogate configuration #2443

Merged
merged 1 commit into from
Nov 10, 2021

Conversation

simoncozens
Copy link
Collaborator

interrogate is a handy tool for checking documentation coverage. This configures interrogate with some project-specific defaults.

@anthrotype
Copy link
Member

No idea how this tool works, but I am not convinced that documentation coverage ought to be checked automatically. I don't think that all functions/classes/methods in a project are meant to be exported as public and as such have a docstring attached... Internal-only stuff may well have no docstring or if anything some inline comments for dev use only, but not users of the library.

@simoncozens
Copy link
Collaborator Author

I don't plan to run it automatically. The configuration is just about configuring the tool so that it can be run manually for reporting and finding areas where more documentation is needed. In fact, the point of this configuration is to hide the internal stuff. e.g. without specifying this config:

= Coverage for /Users/simon/others-repos/fonttools/Lib/fontTools/ttLib/tables/ =
------------------------------ Detailed Coverage -------------------------------
| Name                                                |                 Status |
|-----------------------------------------------------|------------------------|
| C_P_A_L_.py (module)                                |                 MISSED |
|   table_C_P_A_L_ (L13)                              |                 MISSED |
|     table_C_P_A_L_.__init__ (L18)                   |                 MISSED |
|     table_C_P_A_L_.decompile (L25)                  |                 MISSED |
|     table_C_P_A_L_.compile (L74)                    |                 MISSED |
|     table_C_P_A_L_.toXML (L159)                     |                 MISSED |
|     table_C_P_A_L_.fromXML (L204)                   |                 MISSED |
|   Color (L236)                                      |                 MISSED |
|     Color.hex (L238)                                |                 MISSED |
|     Color.__repr__ (L241)                           |                 MISSED |
|     Color.toXML (L244)                              |                 MISSED |
|     Color.fromHex (L249)                            |                 MISSED |
|     Color.fromRGBA (L259)                           |                 MISSED |
|-----------------------------------------------------|------------------------|

With this PR:

= Coverage for /Users/simon/others-repos/fonttools/Lib/fontTools/ttLib/tables/ =
------------------------------ Detailed Coverage -------------------------------
| Name                                               |                  Status |
|----------------------------------------------------|-------------------------|
| C_P_A_L_.py                                        |                         |
|   table_C_P_A_L_ (L13)                             |                  MISSED |
|     table_C_P_A_L_.__init__ (L18)                  |                  MISSED |
|   Color (L236)                                     |                  MISSED |
|     Color.hex (L238)                               |                  MISSED |
|     Color.__repr__ (L241)                          |                  MISSED |
|     Color.fromHex (L249)                           |                  MISSED |
|     Color.fromRGBA (L259)                          |                  MISSED |
|----------------------------------------------------|-------------------------|

@anthrotype
Copy link
Member

gotcha, thanks for the clarification.

@simoncozens simoncozens merged commit b29ae80 into fonttools:main Nov 10, 2021
@simoncozens simoncozens deleted the interrogate branch November 10, 2021 10:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants