[Bf-taskforce25] Developer Docs

[Nathan Letwory]

joe wrote:
> Well, we need to avoid over-cluttering our code with
> specially-formatted large comments.
> 
> On Sat, Jul 25, 2009 at 3:07 AM, Wahooney<wahooney at wahooney.net> wrote:
>> What about using doxygen? I know it needs a time investment to get it
>> going, but once it's up it should be easy enough to maintain.

Besides, outdated and/or wrong code documentation is possibly even worse 
than missing external documentation.

/Nathan

>>
>> Joshua Leung wrote:
>>> Hi,
>>>
>>> Very true.... docs have kindof fallen by the wayside, and I suspect
>>> that only a handful of us know the full extent of how most of
>>> everything works regarding all this stuff.
>>>
>>> Even so, I know I spent about 3 days reading through various commits +
>>> the code used in many places before I figured out how to get UI's for
>>> various editors written with the new layout engine from C (at the
>>> time, all the layouts had been converted to Python already, but there
>>> was some stuff that wasn't that easily wrapped in RNA at the time).
>>> However, even now I'm still baffled by how/where the context for the
>>> buttons window actually gets set...
>>>
>>> I should point out here though, that the example you gave about the
>>> Action Editor is not actually correct anymore, since I have converted
>>> it to use the new layout engine stuff (c-api not py though).
>>>
>>>
>>> Regards,
>>> Joshua
>>>
>>> On Sat, Jul 25, 2009 at 12:08 PM, Roland Hess <me at harkyman.com
>>> <mailto:me at harkyman.com>> wrote:
>>>
>>>     Howdy. I've been looking ahead to some down time before my next
>>>     project
>>>     kicks in, and was hoping to spend it doing some work on 2.5 (maybe
>>>     operator-i-fying some armature and anim stuff, python-i-fying headers,
>>>     etc.) but have run into a snag. It seems as though the developer docs
>>>     that were quite popular at the beginning of this whole project have
>>>     fallen behind the times. I tried to work through these projects by
>>>     simply reading the code, but without anything at all to guide (i.e.
>>>     comments in the code), I'm getting the feeling that it's just too much
>>>     work for the time I have available.
>>>
>>>     What would be great from a returning developer's point of view
>>>     (and I'm
>>>     sure it would benefit future devs as well), would be to have
>>>     examples of
>>>     some of the new structures well-documented within the code. For
>>>     example,
>>>     when adding header menus and elements for a new space type (Action
>>>     space
>>>     still uses the old structure) it would be instructive to have at least
>>>     one of the other existing space types that has already been converted
>>>     have explanatory comments within the code. I realize that for those of
>>>     you who came up with the concepts for how all of this new stuff works
>>>     internally, this is pretty simple and obvious stuff. For those of
>>>     us who
>>>     would like to pitch in, though, there is no doc that says:
>>>     python-based
>>>     header menus require items 1,2,3 and a,b,c. I suppose that one could
>>>     really take a couple of weeks, read all of the code, figure out what's
>>>     relevant and what isn't, what's canon and what's a hack, and then
>>>     start
>>>     pecking away with trial and error until the light goes on. However, I
>>>     think it would be much better if the way this stuff works were
>>>     actually
>>>     written down somewhere.
>>>
>>>     Not sure how many people are in my same boat, i.e. if I understand the
>>>     structure and specs I can do the work. It might be a lot. It might be
>>>     just me. From the looks of things, there is plenty of dev help at this
>>>     point, so it might not even be worth the time to really document these
>>>     new processes.
>>>
>>>     Anyway, thanks for listening.
>>>     Roland Hess
>>>     harkyman
>>>     _______________________________________________
>>>     Bf-taskforce25 mailing list
>>>     Bf-taskforce25 at blender.org <mailto:Bf-taskforce25 at blender.org>
>>>     http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>>
>>>
>>> ------------------------------------------------------------------------
>>>
>>> _______________________________________________
>>> Bf-taskforce25 mailing list
>>> Bf-taskforce25 at blender.org
>>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>>
>> _______________________________________________
>> Bf-taskforce25 mailing list
>> Bf-taskforce25 at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-taskforce25
>>
> _______________________________________________
> Bf-taskforce25 mailing list
> Bf-taskforce25 at blender.org
> http://lists.blender.org/mailman/listinfo/bf-taskforce25
> 


-- 

Nathan Letwory

http://www.planetblender.org | http://www.blender-fi.org