From: Ian D R. <id...@cs...> - 2002-01-17 23:49:40
|
On Thu, Jan 17, 2002 at 03:11:46PM -0800, David Bronaugh wrote: > Perhaps a good idea here would be to have some sort of a function > documentation tracking project.. I have been doing a hell of a lot of PHP > programming lately, and I'd be willing to put in the time to get something > like this up and going (the idea would be that you could submit > comments/information on specific functions, then there could be a list of > links to those functions on another page, so that people could easily find > what others have contributed about that function). As well, I guess there > could be some sort of general overview section (I'm not clear at this time > how that'd work). This would probably be a great idea, with a little tweaking. One problem is maintaining useful documentation in, basically, two places. It might be better to gradually add documentation to the source that could be automatically be extracted by something like c2man. Then have a page for each CVS tag, branch, etc. that would nightly extract the documentation and webify it. Then people could submit comments, like with the FAQ, for each function. This has a couple of advantages and a few disadvantages. First, the disadvantage is that it would be a fair amount more work to get it going. Changes would need to be made to the source, more scripts would need to be written, and we would need a system that could be used to extract the documentation from several trees on (at least) a nightly basis. On the plus side, as developers are doing bleeding edge work (such as on the mach64 or mesa-4-0 branches) they only to adjust documentation in one place. Not only that but people digging in the code may only have read documenation in one place. Thoughts? -- Tell it to the Marines! |