[hibernate-dev] Realising the JavaDoc jars as well

[andrea boriero]

+1 for filtering out internal packages.

not a strong opinion on grouping

On 24 December 2017 at 14:23, Steve Ebersole <steve at hibernate.org> wrote:

> 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
> >
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>