[Bf-committers] Request for Comments: Community-Driven Blender DNA Source Code Documentation

[homac]

Hello There!


As some of you know, I've implemented a toolkit, consisting of a code 
generator and a runtime I/O module to map the full Blender DNA to Java 
classes and allow reading and writing of files (cf. [1]).

All that is fine but won't help a developer as long as he/she don't know 
the meaning of those generated classes and its member variables. Thus, 
they will need source code documentation, to be provided in the 
generated code.

Since providing documentation to blender sources is not the right way, I 
came up with the idea to provide a documentation system, maintained 
separate from blender source. I picked that up in the Minecraft modder 
community, and thought it is a neat idea. There, it is basically a 
string table, which maps names of classes and their members to 
deobfuscated names (and the same for documentation, if I remember correct).

I took that idea and made it a bit more flexible, and object oriented, 
added mechanisms such as merging and inheritance of documentation, 
combined it with a versioning system and took JSON as basic format.

Then I've extracted available documentation from python API (thanks to 
Ton's advice) and source code using doxygen into my documentation system 
to fed it to my code generator. Both is not satisfying: Python API 
actually provides documentation of RNA, which is quite similar to DNA 
but still different, and the source code documentation is not addressed 
to API developers, since DNA is not intended to be available to them, I 
guess.

Thus, I still have huge gaps in the documentation that have to be added 
manually, somehow, but I can't provide it on my own (I'm already way off 
track with this thing). To prevent wasting a lot of time of API 
developers by forcing everyone of them to read blender source code to 
figure out what they can actually do with the data, I'm planning to 
setup some kind of community-driven source code documentation system 
similar to a wiki, based on what I already have. My current idea is to 
just host the JSON files in a separate repository on github so everybody 
can easily share knowledge gained from studying blender source code by 
sending in pull requests [2].

When I mentioned that idea on a forum, someone pointed out, that others, 
e.g. the C language guys, might be interested in the documentation as 
well and I should discuss it with you for more elaborated input. Since 
this is a bit of a longer story, and even non-blender developers may 
want to throw in their thoughts, I decided to post it on the mailing list.

So, what do you think about the idea? Are you interested to support it 
from your side or even contribute to it? Or do you rather want to host 
it yourself?

The documentation could even be turned into wiki entries, if you want, 
since it is in machine readable format.




Regards
  Holger Machens



[1] http://homac.cakelab.org/projects/JavaBlend/
[2] https://help.github.com/articles/using-pull-requests/