[Bf-committers] Code readablity

[Ton Roosendaal]

Hi,

The imbuf_types.h is a lot better this way!
Sorry, I forgot to check loadamiga... but there's still an overload of  
comments... let the code talk itself too.

Simple lines as:

	mem = iffmem;

don't need a doxy comment:  "The memory address to the data is copied  
into mem"

or

	bmhd.w = 0;

"The w member of the BitMapHeader is initialized to 0 because it will  
be tested to see if it has been set later."

or

		if (ibuf->cmap){
			if ((flags & IB_cmap) == 0) IMB_applycmap(ibuf);

"If the image has a color map, apply it"

-------

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.

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.

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.

-Ton-


On Friday, Jun 6, 2003, at 05:29 Europe/Amsterdam, Casey Corn wrote:

> Hello all,
>
> I've re-committed the IMB_imbuf_types.h with hopefully
> clearer docs which (hopefully) preserve the code
> readablity.
>
> Ton, could you please check this out to see if this is
> acceptable?  Also, I don't know if you remembered to
> check the imb_loadamiga function for readability as
> well.  I'd like some feedback (from Ton or anyone else
> who has an opinion :) ) before I start documenting
> more functions, to avoid re-work.  I'm relatively new
> to coding, so what may seem like the right amount of
> docs for me might be way overboard :) .
>
> Thanks!
> Casey
>
> __________________________________
> 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