> > > We do that in Sage and it works very well--the reference manual is > thousands of pages long, nearly all from function docstrings. > >> That doesn't *quite* all the time with >> Cython, but I think it could work great in some types of situations. >> >> Experiment: >> >> class WraparoundDirective(CompilerDirective): # in Options.py >> """ >> wraparound >> >> information about the wraparound compiler directive >> """ >> >> class ForInStatNode(Node): # In Nodes.py >> """ >> Python-style for-loop >> >> more info >> >> TAGS: pythoncompatible, loops >> """ >> >> >> Some transforms would fit for documenting language features as well: >> >> class ForloopOptimizations(CythonTransform): >> """ >> Optimizations done to for-loops: >> >> - for in range is ... >> """ > > No offense intended (as this was clearly marked as an experiment) but > I have to admit this feels rather contrived, especially if we end up > making classes/structuring code just to hold the docstrings of user- > level abstractions. I think it would lead to a sparse scattering of > documentation throughout the codebase (most of the code does *not* > need to be exposed to the user documentation, e.g. all the Nodes that > represent Python nodes, and most transforms). The comments/doctests > in the code should probably be about the code itself (useful to a > cython developer, but probably not to a cython user).
[I hit send too soon] It feels a bit as if one put the documentation for the Python language into the source of the CPython interpreter. - Robert _______________________________________________ Cython-dev mailing list [email protected] http://codespeak.net/mailman/listinfo/cython-dev
