[Bf-taskforce25] Developer Docs

[joe]

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.
>
> 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
>