search

DiffusionMapsAcademics / pyDiffMap

Library for diffusion maps
MIT License
46 stars 14 forks source link

Doc Strings Need Example Usage #4

Closed ehthiede closed 6 years ago

ehthiede commented 6 years ago

The current doc strings have Parameters and Returns sections. However, they don't have an Examples section. We should have them.

Currently, the docstrings obey the numpy convention, which you can read about here. There is also an example of a docstring obeying this format here.

ralfbanisch commented 6 years ago

I'm not sure how to best do this. Our functions are quite high level - it's not like we simply add two numbers or something, we perform a rather sophisticated analysis on datasets that often have to be generated or pulled first. In scikit-learn, high level classification or regression functions don't have examples in the API. Rather, the API simply links to example notebooks. Should we do the same?

Alternatively, where should examples go? In the doc string of the class? Or in the doc string of each routine of said class? Very often however, the routines don't really make sense on their own. For example, fit(..) doesn't make sense without calling init(...) first.

ehthiede commented 6 years ago

Good point... maybe the way to go is to just link the example notebooks, like sckit-learn, particularly as we're sort of part of that ecosystem.

ehthiede commented 6 years ago

I closed this because in retrospect, I think Ralf is right and this isn't really necessary.