You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@geode.apache.org by Kirk Lund <kl...@pivotal.io> on 2016/08/12 23:31:20 UTC
Publishing of geode javadocs
I can find the following from Google, but this is the javadocs for the M2
release:
http://geode.incubator.apache.org/releases/latest/javadoc/
Does this need manual updating for M3?
Are we publishing nightly javadocs?
When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class, the
javadocs look malformed, so I'd like to review real javadoc html for the
current state of develop.
-Kirk
Re: Publishing of geode javadocs
Posted by Kirk Lund <kl...@pivotal.io>.
Let's start out with external javadocs only. That way the focus is on the
users of Geode. Sound good?
-Kirk
On Mon, Aug 15, 2016 at 3:57 PM, Mark Bretl <as...@gmail.com> wrote:
> I can add 'geode-assembly/build/install/' to the archive step in the
> nightly build or we could create a separate job, if necessary, to add the
> external javadocs. If we add the external javadocs to the current nightly
> build, the perma link would be
> https://builds.apache.org/job/Geode-nightly/lastSuccessfulBuild/artifact/
> geode-assembly/build/install/apache-geode/javadoc/index.html.
> It is only 19MB in size for the external docs.
>
> If we want to add internal ( **/build/docs/javadoc ), that goes up to
> 211MB.
>
> --Mark
>
> On Sun, Aug 14, 2016 at 8:21 PM, Udo Kohlmeyer <uk...@pivotal.io>
> wrote:
>
> > Maybe the review of the Javadoc for any class should be done as part of
> > the final review of a story.
> >
> > Any public facing classes should be checked that the javadoc is correct
> > for the affected classes.
> >
> > That the render correctly in the IDE, I think might be a side affect of
> > making sure that they docs are actually checked.
> >
> > --Udo
> >
> >
> >
> > On 13/08/2016 10:00 AM, Kirk Lund wrote:
> >
> >> We really need to find an automated solution for discovering javadoc
> >> errors
> >> earlier than manual inspection or looking for warnings in the gradle
> >> output.
> >>
> >> We change our build to fail on javadoc errors because it starts to fail
> >> due
> >> to 3rd party library javadocs, but at a minimum there must be some
> >> alternative for enforcing no warnings in the build.
> >>
> >> As for ConfigurationProperties' javadocs, I don't think it's generating
> >> any
> >> warnings but the javadocs contain malformed html so the result is
> clearly
> >> broken. I'm not sure if there's anyway to automate detecting problems
> like
> >> that.
> >>
> >> -Kirk
> >>
> >>
> >> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
> >>
> >> I'm not sure if we're publishing the nightly javadocs anywhere, but you
> >>> can
> >>> build them from source. If you do a ./gradlew build, the external
> >>> javadocs
> >>> are in geode-assembly/build/install/apache-geode/javadoc
> >>>
> >>> -Dan
> >>>
> >>> On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
> >>>
> >>> I can find the following from Google, but this is the javadocs for the
> M2
> >>>> release:
> >>>>
> >>>> http://geode.incubator.apache.org/releases/latest/javadoc/
> >>>>
> >>>> Does this need manual updating for M3?
> >>>>
> >>>> Are we publishing nightly javadocs?
> >>>>
> >>>> When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class,
> >>>> the
> >>>> javadocs look malformed, so I'd like to review real javadoc html for
> the
> >>>> current state of develop.
> >>>>
> >>>> -Kirk
> >>>>
> >>>>
> >
>
Re: Publishing of geode javadocs
Posted by Mark Bretl <as...@gmail.com>.
I can add 'geode-assembly/build/install/' to the archive step in the
nightly build or we could create a separate job, if necessary, to add the
external javadocs. If we add the external javadocs to the current nightly
build, the perma link would be
https://builds.apache.org/job/Geode-nightly/lastSuccessfulBuild/artifact/geode-assembly/build/install/apache-geode/javadoc/index.html.
It is only 19MB in size for the external docs.
If we want to add internal ( **/build/docs/javadoc ), that goes up to 211MB.
--Mark
On Sun, Aug 14, 2016 at 8:21 PM, Udo Kohlmeyer <uk...@pivotal.io>
wrote:
> Maybe the review of the Javadoc for any class should be done as part of
> the final review of a story.
>
> Any public facing classes should be checked that the javadoc is correct
> for the affected classes.
>
> That the render correctly in the IDE, I think might be a side affect of
> making sure that they docs are actually checked.
>
> --Udo
>
>
>
> On 13/08/2016 10:00 AM, Kirk Lund wrote:
>
>> We really need to find an automated solution for discovering javadoc
>> errors
>> earlier than manual inspection or looking for warnings in the gradle
>> output.
>>
>> We change our build to fail on javadoc errors because it starts to fail
>> due
>> to 3rd party library javadocs, but at a minimum there must be some
>> alternative for enforcing no warnings in the build.
>>
>> As for ConfigurationProperties' javadocs, I don't think it's generating
>> any
>> warnings but the javadocs contain malformed html so the result is clearly
>> broken. I'm not sure if there's anyway to automate detecting problems like
>> that.
>>
>> -Kirk
>>
>>
>> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
>>
>> I'm not sure if we're publishing the nightly javadocs anywhere, but you
>>> can
>>> build them from source. If you do a ./gradlew build, the external
>>> javadocs
>>> are in geode-assembly/build/install/apache-geode/javadoc
>>>
>>> -Dan
>>>
>>> On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
>>>
>>> I can find the following from Google, but this is the javadocs for the M2
>>>> release:
>>>>
>>>> http://geode.incubator.apache.org/releases/latest/javadoc/
>>>>
>>>> Does this need manual updating for M3?
>>>>
>>>> Are we publishing nightly javadocs?
>>>>
>>>> When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class,
>>>> the
>>>> javadocs look malformed, so I'd like to review real javadoc html for the
>>>> current state of develop.
>>>>
>>>> -Kirk
>>>>
>>>>
>
Re: Publishing of geode javadocs
Posted by Udo Kohlmeyer <uk...@pivotal.io>.
Maybe the review of the Javadoc for any class should be done as part of
the final review of a story.
Any public facing classes should be checked that the javadoc is correct
for the affected classes.
That the render correctly in the IDE, I think might be a side affect of
making sure that they docs are actually checked.
--Udo
On 13/08/2016 10:00 AM, Kirk Lund wrote:
> We really need to find an automated solution for discovering javadoc errors
> earlier than manual inspection or looking for warnings in the gradle
> output.
>
> We change our build to fail on javadoc errors because it starts to fail due
> to 3rd party library javadocs, but at a minimum there must be some
> alternative for enforcing no warnings in the build.
>
> As for ConfigurationProperties' javadocs, I don't think it's generating any
> warnings but the javadocs contain malformed html so the result is clearly
> broken. I'm not sure if there's anyway to automate detecting problems like
> that.
>
> -Kirk
>
>
> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
>
>> I'm not sure if we're publishing the nightly javadocs anywhere, but you can
>> build them from source. If you do a ./gradlew build, the external javadocs
>> are in geode-assembly/build/install/apache-geode/javadoc
>>
>> -Dan
>>
>> On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
>>
>>> I can find the following from Google, but this is the javadocs for the M2
>>> release:
>>>
>>> http://geode.incubator.apache.org/releases/latest/javadoc/
>>>
>>> Does this need manual updating for M3?
>>>
>>> Are we publishing nightly javadocs?
>>>
>>> When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class, the
>>> javadocs look malformed, so I'd like to review real javadoc html for the
>>> current state of develop.
>>>
>>> -Kirk
>>>
Re: Publishing of geode javadocs
Posted by Kirk Lund <kl...@pivotal.io>.
The javadocs on ConfigurationProperties look fine in the html generated by
gradle, but it doesn't render properly in IntelliJ (some properties have
javadocs that are fine but more complex ones are broken in the IDE). I
think we should prefer having javadocs that are useful both in IDEs and as
html viewed in a browser, and it's fixable (Kevin just looked into this
with me). However, given that it's not borked in the gradle-generated html,
I'm guessing there's no way to automate detecting subtle problems like
this. Anyone else know or have ideas -- like a more sophisticated 3rd party
gradle plugin for javadocs?
-Kirk
On Fri, Aug 12, 2016 at 5:00 PM, Kirk Lund <kl...@pivotal.io> wrote:
> We really need to find an automated solution for discovering javadoc
> errors earlier than manual inspection or looking for warnings in the gradle
> output.
>
> We change our build to fail on javadoc errors because it starts to fail
> due to 3rd party library javadocs, but at a minimum there must be some
> alternative for enforcing no warnings in the build.
>
> As for ConfigurationProperties' javadocs, I don't think it's generating
> any warnings but the javadocs contain malformed html so the result is
> clearly broken. I'm not sure if there's anyway to automate detecting
> problems like that.
>
> -Kirk
>
>
> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
>
>> I'm not sure if we're publishing the nightly javadocs anywhere, but you
>> can
>> build them from source. If you do a ./gradlew build, the external javadocs
>> are in geode-assembly/build/install/apache-geode/javadoc
>>
>> -Dan
>>
>> On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
>>
>> > I can find the following from Google, but this is the javadocs for the
>> M2
>> > release:
>> >
>> > http://geode.incubator.apache.org/releases/latest/javadoc/
>> >
>> > Does this need manual updating for M3?
>> >
>> > Are we publishing nightly javadocs?
>> >
>> > When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class,
>> the
>> > javadocs look malformed, so I'd like to review real javadoc html for the
>> > current state of develop.
>> >
>> > -Kirk
>> >
>>
>
>
Re: Publishing of geode javadocs
Posted by Kirk Lund <kl...@pivotal.io>.
We really need to find an automated solution for discovering javadoc errors
earlier than manual inspection or looking for warnings in the gradle
output.
We change our build to fail on javadoc errors because it starts to fail due
to 3rd party library javadocs, but at a minimum there must be some
alternative for enforcing no warnings in the build.
As for ConfigurationProperties' javadocs, I don't think it's generating any
warnings but the javadocs contain malformed html so the result is clearly
broken. I'm not sure if there's anyway to automate detecting problems like
that.
-Kirk
On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
> I'm not sure if we're publishing the nightly javadocs anywhere, but you can
> build them from source. If you do a ./gradlew build, the external javadocs
> are in geode-assembly/build/install/apache-geode/javadoc
>
> -Dan
>
> On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
>
> > I can find the following from Google, but this is the javadocs for the M2
> > release:
> >
> > http://geode.incubator.apache.org/releases/latest/javadoc/
> >
> > Does this need manual updating for M3?
> >
> > Are we publishing nightly javadocs?
> >
> > When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class, the
> > javadocs look malformed, so I'd like to review real javadoc html for the
> > current state of develop.
> >
> > -Kirk
> >
>
Re: Publishing of geode javadocs
Posted by William Markito <wm...@pivotal.io>.
+1 for that as well.
Sent from my iPhone
> On Aug 12, 2016, at 5:15 PM, Kirk Lund <kl...@pivotal.io> wrote:
>
> +1 I'd love to have this in place. What do others think?
>
>
> On Fri, Aug 12, 2016 at 5:13 PM, Roman Shaposhnik <ro...@shaposhnik.org>
> wrote:
>
>>> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
>>> I'm not sure if we're publishing the nightly javadocs anywhere, but you
>> can
>>> build them from source. If you do a ./gradlew build, the external
>> javadocs
>>> are in geode-assembly/build/install/apache-geode/javadoc
>>
>> One solution that worked well for me before is to have a dedicated Jenkins
>> job on builds.apache.org to build the Java doc. Then you can make Jenkins
>> archive the tree of html and browse it as your nightly JavaDocs.
>>
>> Thanks,
>> Roman.
>>
Re: Publishing of geode javadocs
Posted by Kirk Lund <kl...@pivotal.io>.
+1 I'd love to have this in place. What do others think?
On Fri, Aug 12, 2016 at 5:13 PM, Roman Shaposhnik <ro...@shaposhnik.org>
wrote:
> On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
> > I'm not sure if we're publishing the nightly javadocs anywhere, but you
> can
> > build them from source. If you do a ./gradlew build, the external
> javadocs
> > are in geode-assembly/build/install/apache-geode/javadoc
>
> One solution that worked well for me before is to have a dedicated Jenkins
> job on builds.apache.org to build the Java doc. Then you can make Jenkins
> archive the tree of html and browse it as your nightly JavaDocs.
>
> Thanks,
> Roman.
>
Re: Publishing of geode javadocs
Posted by Roman Shaposhnik <ro...@shaposhnik.org>.
On Fri, Aug 12, 2016 at 4:51 PM, Dan Smith <ds...@pivotal.io> wrote:
> I'm not sure if we're publishing the nightly javadocs anywhere, but you can
> build them from source. If you do a ./gradlew build, the external javadocs
> are in geode-assembly/build/install/apache-geode/javadoc
One solution that worked well for me before is to have a dedicated Jenkins
job on builds.apache.org to build the Java doc. Then you can make Jenkins
archive the tree of html and browse it as your nightly JavaDocs.
Thanks,
Roman.
Re: Publishing of geode javadocs
Posted by Dan Smith <ds...@pivotal.io>.
I'm not sure if we're publishing the nightly javadocs anywhere, but you can
build them from source. If you do a ./gradlew build, the external javadocs
are in geode-assembly/build/install/apache-geode/javadoc
-Dan
On Fri, Aug 12, 2016 at 4:31 PM, Kirk Lund <kl...@pivotal.io> wrote:
> I can find the following from Google, but this is the javadocs for the M2
> release:
>
> http://geode.incubator.apache.org/releases/latest/javadoc/
>
> Does this need manual updating for M3?
>
> Are we publishing nightly javadocs?
>
> When I use CTRL-J (in IntelliJ) on the ConfiguratingProperties class, the
> javadocs look malformed, so I'd like to review real javadoc html for the
> current state of develop.
>
> -Kirk
>