forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <>
Subject Re: Forrest is overdocumented
Date Wed, 13 Nov 2002 14:13:59 GMT
> 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.  

<doc-depend class="org.apache.bla" method="doda(int)"/> in the low level 

At the high level you should be including sections of the low level docs 
(DONT REPEAT YOURSELF) and then <doc-depend doc="blabla.xml" 
section="bla"/> -- 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...


> Diana

View raw message