Docstring code examples should execute

ELVIS-Project / vis-framework

Thoroughly modern symbolic musical data analysis suite.

http://elvisproject.ca/

31 stars 6 forks source link

Docstring code examples should execute #319

Closed crantila closed 8 years ago

crantila commented 10 years ago

The docstring code examples aren't executable code. They should be.

crantila commented 9 years ago

This isn't necessary for the 2.0.0 release. As long as the examples are correct, I think that's good enough for now. So I'm moving this to the "2.x Documentation" milestone.

musicus commented 8 years ago

Always!

minamouse commented 8 years ago

All the docstring examples? Or are there specific ones?

crantila commented 8 years ago

All. They needn't be particularly useful, but the expectation of experienced Python users is that any sample code in documentation should be executable.

musicus commented 8 years ago

Yes, all.

minamouse commented 8 years ago

Also, what parts of the code should actually have examples? Right now it looks like 1) mostly only run() has examples, which makes sense because it is the part people will be interacting with the most when using VIS and 2) there are a couple of indexer_func() with examples, but it's pretty unlikely that anybody not working on VIS is actually going to need that. So, am I making these examples for users or VIS developers?

musicus commented 8 years ago

Proceed at what we just discussed.

crantila commented 8 years ago

What did you just discuss?

My model for good API documentation, for a long time, has been Qt. See this as an example. The idea is this:

one-sentence description
parameter type and description
if the function raises any exceptions, mention this
further prose description, if required
an example, or some examples, depending on the complexity of the function

minamouse commented 8 years ago

OK, I added examples in everything except for:

ngram (because it's deprecated)
dissonance (the tests for this are failing for me, so I'll add it as soon as I figure this out)
lilypond, dendrogram, barchart (are these going to be used very much anymore once the VIS-Ualizer is ready?)

musicus commented 8 years ago

I'm assuming you did the new_ngram? Ok on dissonance indexer, and Point 3, yes VIS-Ualizer will overtake these. 😸

minamouse commented 8 years ago

Yes, new_ngram is done. So I can close the issue once I do dissonance indexer? Or is there anything else I'm forgetting?

minamouse commented 8 years ago

Done, in my branch.

musicus commented 8 years ago

It should only close when it is merged into main ... if you set it up appropriately the issue will be closed automatically at that point. Look it up.