[hibernate-dev] Realising the JavaDoc jars as well

[Sanne Grinovero]

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:

What I meant to suggest is:
if we agree that we're not going to bother with publishing javadocs
for "internal", we're effectively getting rid of one of the 3
"groups"; one to go..

Personally I believe the SPI/API package differentiation is a gray
area anough to not need physical separation of javadoc archives, so
I'd just make a single javadoc output for all SPI/API.


> Should internal packages be generated into the javadocs (individual and/or
> aggregated)?
> 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.

+1 to keep it simple, for both us and users: I don't think people will
want to learn about the techniques we use to keep our projects organized
as a pre-requisite to be able to find the javadocs they are after.

Thanks,
Sanne


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