I started new thread on this to help keep discussionn on topics more narrow, I hope nobody minds this:
Proposed layout: Description (full) Parameter List Return Values Changelog Examples See Also The two major differnces in opions I saw were where Paramater List and Changelog located at. I'm rather favoring moving the Parameter List above the Description (full). My reasoning is that when one reads the description, which often references the parameters, it makes sense that the parameters purpose is read first. There probably would have to be a policy to keep pararmeter definitions brief, as to avoid long paragaphs. The other change I'd would prefer, is having changelog last. It usually contains last minute information, that one would seek in finding compatiblity changes. They seem not as signifcant as the current information, but very useful to have. And to add to the layout, would be to add a 'notes' section to the layout. Although nifty to break a paragraph to remind someone about a 'gotcha' note. It could be more reliable to have a standard place to put these. Do note: A lot of these opinions are based off of the standard man pages found on unix. The *full* doc layout will then be: Name Description [brief] (refpurpos if defined) proto definition Parameter List Return Values Descriptionn [full] Notes Example See Also Changelog Curt -- First, let me assure you that this is not one of those shady pyramid schemes you've been hearing about. No, sir. Our model is the trapezoid!
