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

[Steve Ebersole]

On Thu 12 Jan 2012 03:19:29 AM CST, Hardy Ferentschik wrote:
> 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

I agree, we should do a redirect.  I had not planned on changing the 
physical dir until 4.1 as that is when the new docs would be getting 
used.  6 in one... if you feel the itch, go for it.


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


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

Just a minor point.  If you run it from the release module, it has to be 
`../gradlew aggregateJavadocs`

Alternatively from root you could run `./gradlew :release: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 think Strong only changed that to move jandex to the provided 
configuration.  I was able to run these fine when I did the build.


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

Hmm, I spent a lot of time getting those right. 
https://fisheye2.atlassian.com/changelog/Hibernate-Core?cs=39d47c4b39f231435305b47e23f4b2cf8e9aede8#releaseZ002frelease.gradle

If they are back, something after fucked those changes up.


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

We should update that in the source tree.  But to be honest, hem docs 
should really just go away as a separate thing.  Their content should be 
merged into the main docs.


>
>
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
-- 
steve at hibernate.org
http://hibernate.org