Please don't commit broken javadocs

[Kirk Lund <kl...@apache.org>]

I'm seeing newly broken javadocs being committed.

:geode-core:javadoc
/Users/klund/dev/gemfire/open/geode-core/src/main/java/org/apache/geode/internal/cache/tier/sockets/MessageExecutionContext.java:91:
warning - @return tag has no arguments.
1 warning

:geode-protobuf:javadoc/tmp/build/ae3c03f4/geode/geode-protobuf/src/main/java/org/apache/geode/protocol/protobuf/utilities/ProtobufUtilities.java:101:
warning - Tag @link: reference not found: BasicTypes.Entry

:geode-assembly:docs
/Users/klund/dev/gemfire/open/geode-protobuf/src/main/java/org/apache/geode/protocol/protobuf/utilities/ProtobufUtilities.java:101:
warning - Tag @link: reference not found: BasicTypes.Entry
1 warning

(The assembly module seem to duplicate javadocs -- I have no idea why but
that could be contributing to our stupidly long build time)

My personal IntelliJ configuration is setup to NOT automatically create
javadoc stubs for me -- if you enable that but don't fill those in then
they generate build warnings like the above.

You can also enable IntelliJ inspections to mark broken javadocs with RED
or YELLOW which can help avoid committing broken javadocs.

Thanks,
Kirk

Re: Please don't commit broken javadocs

[Galen O'Sullivan <go...@pivotal.io>]

We'll move everything to internal soon, before public release.

We have a ticket to fix the Javadocs and the links will be removed soon as
well. The broken links are for generated files that don't seem to have been
created when the javadoc task runs.

On Fri, Sep 22, 2017 at 2:27 PM, Dan Smith <ds...@pivotal.io> wrote:

> Regarding the duplicate javadocs from geode-assembly - geode-assembly
> builds the public javadocs for all of geode. Each module also builds it's
> own javadocs which includes all of the internal methods.
>
> That does point out that everything in geode-protobuf seems to be in non
> internal packages, meaning that it's technically part of the public API. I
> think this came up before that this stuff should be part of an internal
> package. Is anyone working on fixing that?
>
> -Dan
>
> On Fri, Sep 22, 2017 at 2:11 PM, Kirk Lund <kl...@apache.org> wrote:
>
> > I'm seeing newly broken javadocs being committed.
> >
> > :geode-core:javadoc
> > /Users/klund/dev/gemfire/open/geode-core/src/main/java/org/
> > apache/geode/internal/cache/tier/sockets/MessageExecutionContext.java:
> 91:
> > warning - @return tag has no arguments.
> > 1 warning
> >
> > :geode-protobuf:javadoc/tmp/build/ae3c03f4/geode/geode-
> > protobuf/src/main/java/org/apache/geode/protocol/protobuf/utilities/
> > ProtobufUtilities.java:101:
> > warning - Tag @link: reference not found: BasicTypes.Entry
> >
> > :geode-assembly:docs
> > /Users/klund/dev/gemfire/open/geode-protobuf/src/main/java/
> > org/apache/geode/protocol/protobuf/utilities/ProtobufUtilities.java:101:
> > warning - Tag @link: reference not found: BasicTypes.Entry
> > 1 warning
> >
> > (The assembly module seem to duplicate javadocs -- I have no idea why but
> > that could be contributing to our stupidly long build time)
> >
> > My personal IntelliJ configuration is setup to NOT automatically create
> > javadoc stubs for me -- if you enable that but don't fill those in then
> > they generate build warnings like the above.
> >
> > You can also enable IntelliJ inspections to mark broken javadocs with RED
> > or YELLOW which can help avoid committing broken javadocs.
> >
> > Thanks,
> > Kirk
> >
>

Re: Please don't commit broken javadocs

[Dan Smith <ds...@pivotal.io>]

Regarding the duplicate javadocs from geode-assembly - geode-assembly
builds the public javadocs for all of geode. Each module also builds it's
own javadocs which includes all of the internal methods.

That does point out that everything in geode-protobuf seems to be in non
internal packages, meaning that it's technically part of the public API. I
think this came up before that this stuff should be part of an internal
package. Is anyone working on fixing that?

-Dan

On Fri, Sep 22, 2017 at 2:11 PM, Kirk Lund <kl...@apache.org> wrote:

> I'm seeing newly broken javadocs being committed.
>
> :geode-core:javadoc
> /Users/klund/dev/gemfire/open/geode-core/src/main/java/org/
> apache/geode/internal/cache/tier/sockets/MessageExecutionContext.java:91:
> warning - @return tag has no arguments.
> 1 warning
>
> :geode-protobuf:javadoc/tmp/build/ae3c03f4/geode/geode-
> protobuf/src/main/java/org/apache/geode/protocol/protobuf/utilities/
> ProtobufUtilities.java:101:
> warning - Tag @link: reference not found: BasicTypes.Entry
>
> :geode-assembly:docs
> /Users/klund/dev/gemfire/open/geode-protobuf/src/main/java/
> org/apache/geode/protocol/protobuf/utilities/ProtobufUtilities.java:101:
> warning - Tag @link: reference not found: BasicTypes.Entry
> 1 warning
>
> (The assembly module seem to duplicate javadocs -- I have no idea why but
> that could be contributing to our stupidly long build time)
>
> My personal IntelliJ configuration is setup to NOT automatically create
> javadoc stubs for me -- if you enable that but don't fill those in then
> they generate build warnings like the above.
>
> You can also enable IntelliJ inspections to mark broken javadocs with RED
> or YELLOW which can help avoid committing broken javadocs.
>
> Thanks,
> Kirk
>