[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Sc-devel] SC3.2 deadline approaching

Will we not have to accept that the developer deletes some of what the Helper generates
(all kinds of methods that are not interesting to document) and just fills in the crucial stuff?

The only methods that should not be documented are 'private' ones, i.e. those not intended for direct user utilisation. Since SC does not have a formal method for making methods private, I think we'll have to live with this.

But come on, most classes don't have that many methods, and only a few private ones. It's much better to just take the time and do it right when a help file is added. The currently common 'do it halfway' approach leads to worse documentation and maintenance nightmares IMO.

Of course, Helper is intended to automagically generate a template, not a help file. The help file is up to the developer.
So you can decide what you don't want to document by deleting things. This should apply only to private methods.
The only other situation I encountered is when I have some experimental methods: I have not documented them because they are (still) not to be used, so to say.
But, indeed, it would be better to clean the source, I guess.
(I have to say that having all the structure already generated helped me also in being more consistent with names and descriptions)

Thor, do you think I have to rework a bit the help files?



Sc-devel mailing list

Andrea Valle
Università degli Studi di Torino

Think of it as seasoning
. noise [salt] is boring
. F(blah) [food without salt] can be boring
. F(noise, blah) can be really tasty
(Ken Perlin on noise)