On Wed, Aug 18, 2010 at 9:01 AM, Stephen Swaney <[email protected]> wrote: > On Mon, Aug 16, 2010 at 05:46:26PM +0200, neXyon wrote: >> 2) Have a database with a nice structure to store docs >> >> Advantages: >> * Easy to edit for everybody, there could be a web interface to edit >> docs directly >> * Lower binary size >> Disadvantages: >> * No docstrings, so no direct documentation in the interpreter, although >> the help function could be overwritten to retrieve the docs from the DB > > Not having docstrings is a *major* drawback. Not only are they expected > to be there, they are one of the features that makes developing python > code an enjoyable experience. > > -- > Stephen Swaney > [email protected]
Firstly I'd like to postpone any big changed to the doc system for a while (until 2.5 is more on track). While the current system is a bit strange its very easy to maintain for me with a single script that extracts docs and builds the API reference. If docs in blenders source becomes a problem I'm open to having them stored externally and use a "class.attr" key to retrieve them for tooltips and python. Its probably possible to get these external docstrings from the python api dynamically. examples of how it could work. - for builtin types getattr can check for "__doc__" and return an external string. - rna functions can can have their own "__doc__" getattr too. - C methods are not so easy since thir docs are defined on creation but we could re-assign string like objects after PyType_Ready is called which access the full description when __str__ is called on them. - class.__dict__ could use a dict subclass which intercepts __doc__ too, I rather not do this but just pointing it out as a possible way to dynamically provide docs. Currently a dict-subclass is used with operators so properties are shown in the order they are defined. _______________________________________________ Bf-committers mailing list [email protected] http://lists.blender.org/mailman/listinfo/bf-committers
