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

[Mahler T. <tho...@it...>]

Hi again,

> > 
> 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
> 

Ok, now I see clearer: Your prosal covered only the package level but not
the class level (or component level).
I totally agree on this documentation structure !

> 
> > 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 ( :-) ) ...

I agree. And you will find some example for this in OJB. But there are of
course places where several components are kept in one package. But this may
well be a result of the documentation process:
a feedback that things are not separated cleanly enough to have a consistent
package level documentation paradigma.
If we find such "dark spots" we should take this as an opportunity for
refactoring.

> > (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)

That's good! Once we identify such groups we may decide if it makes sense to
create a new subpackage.

> - 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.

that's a good approach to deal with changing (improving !) structures.

> 
> 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.
>  

Yes, general concepts, tutorials, overviews are also needed.
 

> 
> > > 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.)

Using XSLT we can thus provide user specific perspectives on the
documentation. 

> 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...

Yup, that makes sense too...

> 
> > 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.
> 

thanks for the links! 


cu,

Thomas