AW: [Objectbridge-jdo-dev] documentation of java packages

[Budde, F. <fri...@vi...>]

Hi,

> 
> > Too much/little detail?
> 
> Maybe we need more indepth information (see my old
> http://objectbridge.sourceforge.net/system/objectcache.html where I'm
> explaining the softreference mechanism)
> But maybe it's better to have such details not on the package level ?
> 
> > Which kind of documentation did you miss?
> 
> in my old system docs I used the following structure:
> - what it does 
> - how it works
> - write your own implementations
> 
> For me the "how it works" part is not covered enough.
> Again: maybe its better not have this kind of information on 
> the package
> level.
> 
I think package level documentation should not be as detailed as 
class level documentation. It should focus on on classes and their
interaction as a whole. (This is an application of the 
DRY (Don't Repeat Yourself) principle.) Anyone who wants to know 
how a class works internally should refer to the class level javadoc
or the source code. Instead of explaining low level details we could
include a link to the javadoc then the information is just a click away


> For the ojb.broker.cache package your apporach works fine!
> But: 
> 1. there are packages that contains much more classes that 
> have only little
> logical coherence (e.g. the ojb.broker.util package).
> 2. There are packages that contain more classes that are 
> focussed on more
> than one logical component.
> 
> The package view will only provide a rough overview.
> I see two options:
> 1. create suppackages grouped around one logical component 

Isn't that the way it's meant to be ( :-) ) ...

> (this will be
> very difficult if not impossible for packages like the util package)
> 2. Introduce an additional level of documentation below the 
> package level.
> Say a "component" level.
> 

I'd prefer lots of little packages over big packages which contain more
than one concept  (Thomas: This wasn't hard to guess since you know my
style of programming :-) ). Nevertheless I see the advantages of grouping
a lot of helper classes into a util package. I'd propose 
- trying to group these classes (if that is possible)
- writing a separate package level documentation for each group
- writing a separate package level documentation for the rest of
  the classes which do not belong to any of the groups mentioned above
- writing a package.html file for the package that contains descriptions
  of the groups and links to the 'real' documentation.
This approach would provide for easy refactoring. Simply put all 
classes mentioned in the documentation in a separate package and
move the documentation describing these classes in that package as well.

Nevertheless I think Thomas is right when he said that there exist
kinds of documentation which do not fit well into package level
documentation e.g. information which cover the whole or a major
part of OJB. What about having some extra documents like concepts
or (similar to the jdc) trails which have a broader scope than
package or class level documentation.
  

> > Is the information presented in the right order/hierachy?
> 
> I guess It depends on the focus you have if the order seems right. 
> I would prefer to have the  conceptual things at the top of 
> the document,
> like in this structure:
> 
> Intent
> Detailed Description
> Diagramms
> Patterns used
> Dependencies on other packages
> Hints for extending and maintaining this package
> Todo
> 
> But I can imagine that others are more interested to see a 
> more structural
> overview first. 
> 
If you don't miss a whole section then it's easy to change
the order of sections within the xml files (I'll happily
supply a xsl stylesheet which will reorder the sections.)
The problem is that the first time you look into 
package level documentation you'll probably want to get an
overview. Once you've understood the concepts and start using
or changing the package you'll probably want to have a look 
at the details...

> Where can I get the docbook dtd (or xsd) ?
> 
http://www.oasis-open.org/docbook/#documents
Also have a look at
http://www.docbook.org
where you'll find a html version of the book
"DocBook: The Definitive Guide"
And last but not least
www.nwalsh.com and http://sourceforge.net/projects/docbook
which contain a wealth of tools and valuable
information about docbook.


  Frido

PS: I'd like to thank everyone for the comments on the documentation format.