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

Added docstrings to AIPlugIn #98

Merged
merged 5 commits into from
Dec 18, 2024

Conversation

asgibson
Copy link
Contributor

Here is an update for ai_plugin.py using Google style docstrings. Also using type annotations.

Is this the style we'd like to go forward with?
There are other style choices we could choose. i.e., NumPy, reST, or Epytext (others?)

Opinions?

@asgibson asgibson added documentation Improvements or additions to documentation enhancement New feature or request question Further information is requested convention Repository coding and documentation standards labels Dec 12, 2023
@asgibson asgibson self-assigned this Dec 12, 2023
@asgibson asgibson linked an issue Dec 12, 2023 that may be closed by this pull request
@codecov-commenter
Copy link

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (822cd97) 100.00% compared to head (4430d0f) 100.00%.

Additional details and impacted files
@@            Coverage Diff            @@
##              main       #98   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           25        25           
  Lines          938       937    -1     
  Branches       129       129           
=========================================
- Hits           938       937    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@asgibson asgibson added the help wanted Extra attention is needed label Dec 12, 2023
@the-other-james
Copy link
Contributor

I don't have a strong preference for the comment style we use. If I had to pick, I would go with whatever the python libraries use.

@asgibson
Copy link
Contributor Author

We have decided to follow numpydoc style:
https://numpydoc.readthedocs.io/en/latest/format.html

@dragonejt
Copy link
Contributor

Hello, I've been browsing the other PR's and issues in the repository. I just wanted to note that since you all have decided on a docstring style to move forward with, most IDEs now have support for automatically generating docstring formats/templates for you to fill in. Essentially, all you will have to do is type """ and press enter, and a docstring template will be generated based on your function parameters and return values. This will save you a lot of time vs typing out the docstrings in full by yourself.

In VSCode, you can use the autoDocstring extension, which has support for numpydoc.

PyCharm already has automatic docstring templates builtin, and already supports numpydoc.

Module has docstring (pylint)
All methods have docstring (pytlint)
Fixed high_level_data type
Changed update args defaults to None
  removed use of [] and {} (pylint)
@asgibson asgibson force-pushed the 97-add-pep-compliant-docstrings-to-ai_plugin branch from 4430d0f to 009b321 Compare November 18, 2024 20:46
Python 3.8-3.10 need to import Any from typing
AIPlugIn is deprecated, changed to AIPlugin
@asgibson
Copy link
Contributor Author

@dragonejt, thank you for the tool suggestions. As long as people follow the NumPy docstring formatting, they can use whatever tool they want to create them.

@asgibson asgibson requested review from the-other-james and removed request for Evana13G, jlucas9, tjchase34 and cfirth-nasa November 19, 2024 19:27
Copy link
Contributor

@the-other-james the-other-james left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, thank you for getting us on track for having a set style!

Just one small suggestion, otherwise good to merge.

@asgibson asgibson force-pushed the 97-add-pep-compliant-docstrings-to-ai_plugin branch from 174fc28 to e5061d8 Compare December 18, 2024 19:49
@asgibson asgibson merged commit 253d14f into main Dec 18, 2024
20 checks passed
@asgibson asgibson deleted the 97-add-pep-compliant-docstrings-to-ai_plugin branch December 18, 2024 19:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
convention Repository coding and documentation standards documentation Improvements or additions to documentation enhancement New feature or request help wanted Extra attention is needed question Further information is requested
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add PEP compliant docstrings to ai_plugin
4 participants