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

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




On 20 Jan 2008, at 18:35, thor wrote:


Hi all

I'd be very happy to have these in the distribution and serving as the 'official best practice' way to make a help file.

Ok, if we're not worried about bloating, I vote for that as well then. 
I think it encourages... nay forces ... developers to use it.

This would go a long, long way to creating uniformity in the doc (one of the advantages of an autodoc solutions) without losing any of the advantages of the current version.

Please, let's include them rather than make them a Quark! :-)

Andrea will be happy not to have to use SVN : )

A remaining question is that the Helper documents EVERY method in a class.
It will take a developer ages to fill in all the required information to complete the helpfile,
and (s)he will be dead of boredom half way down the page.

I say that's a feature not a problem. It encourages the developer to document all public methods, which is very commonly, and unfortunately, not done. It also makes it much easier to do that.

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.

S.