[hibernate-dev] Realising the JavaDoc jars as well

[Steve Ebersole]

Sure, but the question remains :P  It just adds another one:


   1. Should internal packages be generated into the javadocs (individual
   and/or aggregated)?
   2. Should the individual javadocs (only intended for publishing to
   Central) group the packages into api/spi(/internal) the way we do for the
   aggregated javadocs?

Personally I think filtering out internal packages is a great idea.

Regarding grouping packages, I think its not worth the effort for the
individual ones - just have an overview for these that just notes this
distinction.

On Sat, Dec 23, 2017 at 6:53 AM Sanne Grinovero <sanne at hibernate.org> wrote:

> On 22 December 2017 at 18:16, Steve Ebersole <steve at hibernate.org> wrote:
> > I wanted to get everyone's opinion about the api/spi/internal package
> > grouping we do in the aggregated Javadoc in regards to the per-module
> > javadocs.  Adding this logic adds significant overhead to the process of
> > building the Javadoc, to the point where I am considering not performing
> > that grouping there.
> >
> > Thoughts?
>
> For Hibernate Search we recently decided to not produce javadocs at
> all for "internal"; everything else is just documented as a single
> group.
>
> That cuts on the "need to know" complexity of end users. Advanced
> users who could have benefitted from knowing more about the internals
> will likely have sources.
>
> >
> > On Tue, Dec 12, 2017 at 11:37 AM Vlad Mihalcea <mihalcea.vlad at gmail.com>
> > wrote:
> >>
> >> I tested it locally, and when publishing the jars to Maven local, the
> >> JavaDoc is now included.
> >>
> >> Don't know if there's anything to be done about it.
> >>
> >> Vlad
> >>
> >> On Mon, Dec 11, 2017 at 9:32 PM, Sanne Grinovero <sanne at hibernate.org>
> >> wrote:
> >>
> >> > +1 to merge it (if it works - which I didn't check)
> >> >
> >> > Some history can easily be found:
> >> >  -
> >> >
> http://lists.jboss.org/pipermail/hibernate-dev/2017-January/015758.html
> >> >
> >> > Thanks,
> >> > Sanne
> >> >
> >> >
> >> > On 11 December 2017 at 15:24, Vlad Mihalcea <mihalcea.vlad at gmail.com>
> >> > wrote:
> >> > > Hi,
> >> > >
> >> > > I've noticed this Pull Request which is valid and worth integrating:
> >> > >
> >> > > https://github.com/hibernate/hibernate-orm/pull/2078
> >> > >
> >> > > Before I merge it, I wanted to make sure whether this change was
> >> > accidental
> >> > > or intentional.
> >> > >
> >> > > Was there any reason not to ship the JavaDoc jars along with the
> >> > > release
> >> > > artifacts and the sources jars as well?
> >> > >
> >> > > Thanks,
> >> > > Vlad
> >> > > _______________________________________________
> >> > > hibernate-dev mailing list
> >> > > hibernate-dev at lists.jboss.org
> >> > > https://lists.jboss.org/mailman/listinfo/hibernate-dev
> >> >
> >> _______________________________________________
> >> hibernate-dev mailing list
> >> hibernate-dev at lists.jboss.org
> >> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>