[DISCUSS] audience annotations JDK9+ javadoc generation

[Allen Wittenauer <aw...@apache.org>]

	Thanks to Owen,  pretty much determined the only way to have feature parity under JDK9+ is to extend an internal Java object (specifically DocEnvImpl from jdk.javadoc.internal.tool.DocEnvImpl) . From what we can tell, the new javadoc APIs do not provide a way (easy or otherwise) to remove content from the document tree.  We as a community need to decide how we want to go forward.

	We’re not the only ones to hit this issue but from what we can tell, the Java team isn’t interested in fixing it.

	Some options off the top of my head:
	
	- Go ahead and do the hack. We wouldn’t be the first to do it (see https://github.com/rnc/hiderdoclet/blob/main/doclet/src/main/java/org/goots/hiderdoclet/doclet/DocletEnvironmentProcessor.java which is also ASL 2.0 so we could effectively just lift and modify this code)

	- Remove the Javadoc functionality entirely…. but I’m not sure how useful these annotations become without it.

	- Throw in the towel and just remove the annotations functionality entirely.

	I’m sure there are others.


Thoughts?

Thanks!

Re: [DISCUSS] audience annotations JDK9+ javadoc generation

[Sean Busbey <bu...@apache.org>]

I think we should go with the hack. At least for the projects where
I'm involved, being able to generate selective javadocs is a big
selling point for the audience annotations.

-busbey
the contents of this email should be treated as NOT A CONTRIBUTION
under the ALv2.


On Sat, Apr 9, 2022 at 9:46 PM Allen Wittenauer <aw...@apache.org> wrote:
>
>
>         Thanks to Owen,  pretty much determined the only way to have feature parity under JDK9+ is to extend an internal Java object (specifically DocEnvImpl from jdk.javadoc.internal.tool.DocEnvImpl) . From what we can tell, the new javadoc APIs do not provide a way (easy or otherwise) to remove content from the document tree.  We as a community need to decide how we want to go forward.
>
>         We’re not the only ones to hit this issue but from what we can tell, the Java team isn’t interested in fixing it.
>
>         Some options off the top of my head:
>
>         - Go ahead and do the hack. We wouldn’t be the first to do it (see https://github.com/rnc/hiderdoclet/blob/main/doclet/src/main/java/org/goots/hiderdoclet/doclet/DocletEnvironmentProcessor.java which is also ASL 2.0 so we could effectively just lift and modify this code)
>
>         - Remove the Javadoc functionality entirely…. but I’m not sure how useful these annotations become without it.
>
>         - Throw in the towel and just remove the annotations functionality entirely.
>
>         I’m sure there are others.
>
>
> Thoughts?
>
> Thanks!
>

Re: [DISCUSS] audience annotations JDK9+ javadoc generation

[Nick Dimiduk <nd...@apache.org>]

I think selective javadoc enables an anti-pattern that we should not
encourage. That said, we previously supported the feature, so we should
support it for some transitional period, giving downstream projects notice
of our intention to drop it (if we have such an intention), granting them a
chance to adjust.

I prefer we  continue to support the feature in JDK9+ if possible, but also
document a more hygienic approach going forward. I’ve not yet reviewed the
provided patch, but my understanding is that it enables the feature, even
if using an undesirable method. I think that’s a reasonable compromise,
given the situation we have.

Thanks,
Nick

On Thu, Apr 21, 2022 at 18:51 Allen Wittenauer
<aw...@effectivemachines.com.invalid> wrote:

>
> Sorry things have been hectic in my personal universe. Just a follow-up to
> where this sits today.
>
> * It doesn’t appear that there was a lot of discussion here so I’m
> guessing most people don’t care?
> * I missed that the patch that Owen provided does hack the API.  I
> committed that code change if only to make the source tree build again.
>
> That said, if the community feels strongly about it, we can obviously
> change that.
>
>
>

Re: [DISCUSS] audience annotations JDK9+ javadoc generation

[Allen Wittenauer <aw...@effectivemachines.com.INVALID>]

Sorry things have been hectic in my personal universe. Just a follow-up to where this sits today.

* It doesn’t appear that there was a lot of discussion here so I’m guessing most people don’t care?
* I missed that the patch that Owen provided does hack the API.  I committed that code change if only to make the source tree build again.

That said, if the community feels strongly about it, we can obviously change that.

Re: [DISCUSS] audience annotations JDK9+ javadoc generation

[Akira Ajisaka <aa...@apache.org>]

I'm +1 to remove the Javadoc functionality.

I'm not a fan of hacking the API. It's not a long-term solution.
In addition, personally I don't want selective javadocs. I want to look at
even @Private javadoc to develop Hadoop and its related projects.

-Akira

On Sun, Apr 10, 2022 at 11:46 AM Allen Wittenauer <aw...@apache.org> wrote:

>
>         Thanks to Owen,  pretty much determined the only way to have
> feature parity under JDK9+ is to extend an internal Java object
> (specifically DocEnvImpl from jdk.javadoc.internal.tool.DocEnvImpl) . From
> what we can tell, the new javadoc APIs do not provide a way (easy or
> otherwise) to remove content from the document tree.  We as a community
> need to decide how we want to go forward.
>
>         We’re not the only ones to hit this issue but from what we can
> tell, the Java team isn’t interested in fixing it.
>
>         Some options off the top of my head:
>
>         - Go ahead and do the hack. We wouldn’t be the first to do it (see
> https://github.com/rnc/hiderdoclet/blob/main/doclet/src/main/java/org/goots/hiderdoclet/doclet/DocletEnvironmentProcessor.java
> which is also ASL 2.0 so we could effectively just lift and modify this
> code)
>
>         - Remove the Javadoc functionality entirely…. but I’m not sure how
> useful these annotations become without it.
>
>         - Throw in the towel and just remove the annotations functionality
> entirely.
>
>         I’m sure there are others.
>
>
> Thoughts?
>
> Thanks!
>
>