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

[Ton Roosendaal]

Hi,

I noticed everyone ignored this mail! And that whilst there's something very cool here.

Here's a very sophisticated Blender DNA (and file) doc:
http://homac.cakelab.org/projects/JavaBlend/spec.html

I also find it very interesting to have a java .blend read/writer. Opens up opportunities in many areas! Check on it, recommended :)

Laters,

-Ton-

--------------------------------------------------------
Ton Roosendaal  -  ton at blender.org   -   www.blender.org
Chairman Blender Foundation - Producer Blender Institute
Entrepotdok 57A  -  1018AD Amsterdam  -  The Netherlands



> On 17 Dec, 2015, at 20:30, homac <homac at strace.org> wrote:
> 
> 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/
> 
> 
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> http://lists.blender.org/mailman/listinfo/bf-committers