[Bf-committers] Doxygen project

[Ton Roosendaal]

Hi,

(changed the subject to attract more attention!)

Everyone, please give feedback on doxy strategies... it's nice to say  
"go ahead" but it really involves some more thinking... it especially  
should give a result that's actually *used* by people. Since I'm not  
the typical representative for a coder here, I need you to help casey  
with doing the right stuff.

Right now, my opinion is simple:

- doxify the classes/headers and external API only
- no doxy comments inside the code, but restrict to .h files
- only document what would give additional added value.
- Code readability and layout should never be sacrified

-Ton-


On Friday, Jun 6, 2003, at 19:01 Europe/Amsterdam, Casey Corn wrote:

>> The imbuf_types.h is a lot better this way!
>
> Whew.  I had hoped so :) .
>
>> Sorry, I forgot to check loadamiga... but there's
>> still an overload of comments... let the code talk
>> itself too.
>
> <snip>
>
>> My suggestion is to limit adding doxy comments at a
>> higher level, to at least understand what the
> structs
>> or classes do, and how the module API calls work.
>
> Okay.  I'll stick to documenting the high-level
> purpose.  Do you think that I should stick to the
> stuff which is exposed thru the header files as well?
>
> I will remove the internal docs I added when I get the
> chance, hopefully this weekend.
>
>> Look at what Doxy is in Ghost... I think that's not
>> disturbing at all.  The c-code comments are just
> code
>> comments (not doxyfied) which I think should remain
>> that way.
>
> Okay, I think I understand what you are saying.  I'll
> look more closely at Ghost.
>
>> Please, also provide html doxy examples of how it
>> would look like... I don't have doxy here. Or
> provide
>> an example project with Doxy documentation you would
>> like to use as a reference for what we should aim
> at.
>
> I have an outdated (about 1 week old) version of what
> doxygen outputs for blender at:
>
> http://www.extremezone.com/~frcornrs/doxygen/html/
>
> These docs are the same as what should be produced if
> doxygen is run in the doc directory.  I'll try to
> update the html this weekend as well.
>
> As far as an reference project goes, what would you
> say about using Ghost?  If you would like, I could
> write up a short tutorial about how to use doxygen
> (with links to the output), using Ghost files and
> functions as reference.
>
> Thanks for the feedback!
> Casey
>
> P.S.
> Thanks to sgefant for cleaning up after me.  I guess
> it just goes to show that even if you double and
> triple check everything, things still get through >:(
> .  Sigh.
>
> __________________________________
> Do you Yahoo!?
> Yahoo! Calendar - Free online calendar with sync to Outlook(TM).
> http://calendar.yahoo.com
> _______________________________________________
> Bf-committers mailing list
> Bf-committers@blender.org
> http://www.blender.org/mailman/listinfo/bf-committers
>
>
------------------------------------------------------------------------ 
--
Ton Roosendaal  Blender Foundation ton@blender.org  
http://www.blender.org