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

[Scott Marlow]

Are the doc commits visible on your personal Hibernate fork still?  I 
know that "gitk" will visualize the master branch or whatever branch. 
Maybe you can see the doc commits on the master and a merge that took 
them out (or not ;).

We should be able to "git cherry-pick commit-id" the commits from your 
fork, back to master (if they are still on your branch).

On 01/12/2012 09:58 PM, Steve Ebersole wrote:
> Can anyone with better git-fu than me tell me where those changes went?
>
>
> On Thu 12 Jan 2012 08:44:19 PM CST, Steve Ebersole wrote:
>> 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
>>
>