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

Improve docstrings #127

Open
ArnoStrouwen opened this issue Sep 24, 2023 · 4 comments
Open

Improve docstrings #127

ArnoStrouwen opened this issue Sep 24, 2023 · 4 comments

Comments

@ArnoStrouwen
Copy link
Member

Such that makedocs warnonly = [:missing_docs] can be removed.

@Spinachboul
Copy link

@ArnoStrouwen
Can you also provide the reference for this issue!

@ArnoStrouwen
Copy link
Member Author

Solve these warnings here:
https://github.com/SciML/GlobalSensitivity.jl/blob/master/docs/make.jl#L15
Likely, putting the checkdocs keyword to :exports will get you 90-100% of the way there:
https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs,
since most of the warnings are false positives (we only want to document the external API, not all internals).

@Spinachboul
Copy link

Spinachboul commented Jan 7, 2024

@ArnoStrouwen
So basically, in this code : https://github.com/SciML/GlobalSensitivity.jl/blob/master/docs/make.jl#L15
we have to replace warnonly = [:missing_docs] by checkdocs = :exports.
This change also has to be done in the docs which would reduce the false positive warnings

Please tell me if I am going along the correct lines

@ArnoStrouwen
Copy link
Member Author

By removing the warnonly keyword, Documenter will error when building the documentation if there is anything in the package which does not have a docstring included in the Documentation.
(things like: https://docs.sciml.ai/GlobalSensitivity/stable/methods/morris/)
By setting the checkdocs keyword to exports, it will only error if the missing docstrings are attached to something that is actually exported by the package, which is the behavior we want.

It might be that everything is already included, in that case nothing extra needs to be done.
It might be that a docstring is missing, in which case it needs to be either added to the appropriate place in the methods section of the documentation, or alternatively, it might be something that did not need to be exported.

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

No branches or pull requests

2 participants