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

Revise docstrings #9

Closed
uvchik opened this Issue Nov 25, 2015 · 4 comments

Comments

Projects
None yet
1 participant
@uvchik
Copy link
Member

uvchik commented Nov 25, 2015

State of existing docstrings

(1) no docstring
(2) insufficient docstring, wrong layout
(3) sufficient docstring but wrong layout
(4) seems okay

core/energy_system.py

  • EnergySystem (1)
  • EnergyRegion (1)
  • Simulation (1)

core/network/init.py

  • Entity (2)

core/network/entity/init.py

  • Bus (2)
  • Components (3)

core/network/entity/components/init.py

  • Sink (2)
  • Source (2)
  • Transformer (3)
  • Transport (2)

core/network/entity/components/source.py

  • FixedSource (2)
  • DispatchSource (2):
  • Commodity (2)

demandlib/demand.py

  • electrical_demand (5)
  • methods of electrical_demand (1-3)

Check, revise and ask for support if necessary.

@uvchik uvchik self-assigned this Nov 25, 2015

@uvchik uvchik added this to the December 2015 release milestone Nov 25, 2015

@uvchik

This comment has been minimized.

Copy link
Member Author

uvchik commented Nov 25, 2015

Check numpy documentation and pep 257.

@uvchik

This comment has been minimized.

Copy link
Member Author

uvchik commented Nov 26, 2015

There was an open question at the meeting, where to write the docstring of a class. In pep257 I found:

"The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its init method. Individual methods should be documented by their own docstring."

@uvchik

This comment has been minimized.

Copy link
Member Author

uvchik commented Nov 26, 2015

Searching for numpydoc examples I found examples writing the docstring in the class level instead of in the init method.

Let us use this for future docstrings and change the old ones (if necessary) step by step.

uvchik added a commit that referenced this issue Nov 26, 2015

@uvchik

This comment has been minimized.

Copy link
Member Author

uvchik commented Dec 1, 2015

Completed with commit d3375f0.

@uvchik uvchik closed this Dec 1, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment