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

[Steve Ebersole]

Actually wrt aggregateJavadocs, some how all those edits to 
release.gradle are gone on master :(


On Thu 12 Jan 2012 03:48:46 PM CST, Steve Ebersole wrote:
>
> 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