Return-Path: Delivered-To: apmail-xml-forrest-dev-archive@xml.apache.org Received: (qmail 90984 invoked by uid 500); 13 Nov 2002 14:16:01 -0000 Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: forrest-dev@xml.apache.org Delivered-To: mailing list forrest-dev@xml.apache.org Received: (qmail 90958 invoked from network); 13 Nov 2002 14:16:00 -0000 Received: from unknown (HELO set.superlinksoftware.com) (66.35.175.110) by daedalus.apache.org with SMTP; 13 Nov 2002 14:16:00 -0000 Received: from rdu26-72-100.nc.rr.com ([66.26.72.100]) by set.superlinksoftware.com (JAMES SMTP Server 2.1a1-cvs) with SMTP ID 65 for ; Wed, 13 Nov 2002 08:58:01 -0500 Message-ID: <3DD25E27.5030304@apache.org> Date: Wed, 13 Nov 2002 09:13:59 -0500 From: "Andrew C. Oliver" User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.2b) Gecko/20021016 X-Accept-Language: en-us, en MIME-Version: 1.0 To: forrest-dev@xml.apache.org Subject: Re: Forrest is overdocumented References: <8DD14D16-F703-11D6-9EF5-0030653FE818@apache.org> In-Reply-To: <8DD14D16-F703-11D6-9EF5-0030653FE818@apache.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N > I fear this approach is a bit oversimplistic, paticularly for projects > with large amounts of code. Some docs would have dependencies on > *many* classes. Potential contract violations (revealed during the > build process??) would overwhelm committers/users. You're wrong. This is like saying "import statements" should just be guessed at because worrying about what dependencies the code has will overwhelm the developers/users... (I'm not sure what hte user has to do with the doc part either...the tool is supposed to resolve it) > >> Secondly. Move the documentation as close to the code as possible >> while making the conceptual documentation depend on it! > > > Can you elaborate? Well presumably your documenting lower level concepts at a higher level. Presumably the higher level documentation should DEPEND upon the lower level docuemntation, include portions where possible, and specify dependencies upon it. in the low level docs... At the high level you should be including sections of the low level docs (DONT REPEAT YOURSELF) and then -- Then if the low level doc is broken, the high level doc is marked broken as well. Or if the low level doc deletes that section...the high level doc is broken as well. Furthermore high level docs might depend upon code structures as well. For instance, in the case of ANT if I'm describing how to use the JUNIT task and I'm describing the printsummary attribute, I can obviously refer to that attribute in the low level implementation of the Junit taks (which I think is org.apache.ant.somethingsomething.tasks.JUnitTask.setPrintSummary(bla) ) -- This will catch things like changes in how configuration files work, directory structure, etc. It won't catch functionality changes. If I'm describing how printsummary works and now suddenly it does something different but has the same attributes/etc... This won't catch that. But thats crappy programming probably anyhow. I think this will help reduce the weight of maintaining documentation on developers and its invisible to users anyhow. Its drawback is that it may not always be natural to create a heirarchial structure that this seems to dictate, but I think its clean... The rest of the time the documentation should be as close to the code as possible...I'm not sure how much more I can elaborate on that.... Like Javadoc kinda sorta... -Andy > > Diana > >