[hibernate-dev] Minor issues/questions about Hibernate Core/ORM documentation

[Hardy Ferentschik]

Answers inline

On Jan 12, 2012, at 9:50 AM, Gail Badner wrote:

> I've uploaded the 4.0.1.Final documentatation to http://docs.jboss.org/hibernate/core/4.0/.  
> 
> Maybe this was already discussed but, should the switch from "core" to "orm" affect the URL for the 4.0 documentation (i.e., http://docs.jboss.org/hibernate/orm/4.0/)?

I think it makes sense to switch the urls. However, in this case I suggest we also put a redirect in place for http://docs.jboss.org/hibernate/core/4.0/ to http://docs.jboss.org/hibernate/orm/4.0/
Just renaming the directories is probably not a good idea due to bookmarks and people used to go to the 'core' url. If we change to orm we need to update the pointers from 
http://www.hibernate.org/docs

> Also, I noticed that http://docs.jboss.org/hibernate/stable/core/ points to 3.6.9.Final docs. Should it point to http://docs.jboss.org/hibernate/core/4.0/ (or http://docs.jboss.org/hibernate/orm/4.0/)?

Stable should definitely point to 4.0. That's independent of whether we rename the urls

> I ended up using the documentation downloaded from the SourceForge distribution because I got errors when I tried to build the Javadoc from the 4.0.1 tag using "gradle javadoc":
> 
> /NotBackedUp/gbadner/git/hibernate-core-master/hibernate-core/src/main/java/org/hibernate/metamodel/source/annotations/HibernateDotNames.java:109: cannot find symbol
> symbol  : variable DotName
> location: interface org.hibernate.metamodel.source.annotations.HibernateDotNames
>        DotName ACCESS_TYPE = DotName.createSimple( AccessType.class.getName() );
> 
> What command should be used to build Javadoc?

'gradle javadoc' is the default javadoc task which you get when you use the Java plugin. It build the javadocs for the current module. In our case we don't use this task, because
we want aggregated docs. To get the aggregated docs you need to run the 'aggregateJavadocs' from the release module.

'./gradlew aggregateJavadocs'

FYI, the javadoc task needs all dependencies on the classpath when executing. Looking at the error it seems jandex is not on the classpath. This might be related to HHH-6921, but that's just a guess.
As said, the default javadocs tasks are not configured, because we are only interested in the aggregated docs.

> I also noticed that the Javadoc includes test classes. It would be nice to exclude those.

right, even the aggregated docs seem to include test classes. I would create a jira and we reconfigure the task for the next release

> I really liked how convenient it was to be able to just copy the contents of the documentation directory from the distribution into the staging directory for rsync-ing. The only change I had to make after copying was to change hem/en to hem/en-US. I haven't looked into this, but I imagine that would be an easy thing to fix.

In Search and Validator we made sure that the directory structure of the documentation in the distribution is the same as on the docs server. This way you really just need to rsync and in case of a final release update the stable pointer.
See also https://community.jboss.org/wiki/ReleasingHibernateValidator

Hope this helps :-)

--Hardy