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 API documentation #112

Open
7 of 11 tasks
jobrachem opened this issue Nov 1, 2023 · 0 comments
Open
7 of 11 tasks

Improve API documentation #112

jobrachem opened this issue Nov 1, 2023 · 0 comments
Labels
comp:documentation Improvements or additions to the documentation
Milestone

Comments

@jobrachem
Copy link
Contributor

jobrachem commented Nov 1, 2023

Our API documentation currently is very limited. I think it would be a good investment of our time to improve it. Specifically, that means:

  1. Describe not only what a class/function does, but also put it into context. For example, the lsl.GooseModel is currently described with the sentence "A ModelInterface for a Liesel Model". This sentence adds almost no information on top of the class name. How do you use it? What job does it do?
  2. Classes and methods should be equipped with examples, showcasing common usage.
  3. Where possible, examples should be written as doctests, because that makes sure that examples stay up to date.
  4. We should make frequent use of the "See Also" section.
  5. All parameters should be documented.
  6. All returned values should be documented.

This issue tracks our progress with improving the documentation.

I selected what I think are the most important starting points for improved documentation.

Liesel issues

Goose issues

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
comp:documentation Improvements or additions to the documentation
Projects
None yet
Development

No branches or pull requests

1 participant