I suppose I should update that to use a package-info or similar, though as soon 
as you enter the docs, it has a bold link to “See IoBuilder”. That links to 
https://logging.apache.org/log4j/2.x/log4j-iostreams/apidocs/org/apache/logging/log4j/io/IoBuilder.html
 where the main docs are for this (try to find any other useful docs about this 
module on the website). I distinctly recall documenting everything in this 
module when I added it (you may find a common theme in a lot of the javadocs 
upon inspecting the history). Considering my preference for API docs to include 
useful info, I’ve proposed in the past that we make a custom javadoc plugin to 
generate manual pages for plugins from the docs put on the plugin classes 
themselves (can help with reducing duplication of docs).

> On Feb 14, 2023, at 1:10 PM, Volkan Yazıcı <vol...@yazi.ci> wrote:
> 
> Matt, I am not inclined to publish Javadoc HTMLs for `log4j-iostreams` and
> `log4j-taglib` for the following reasons:
> 
>   - AFAIC, neither has any valuable information in their Javadoc.
>   - Both need a decent developer-friendly short manual page, not a Javadoc
>   HTML that needs to be deciphered by the developer first before being useful.
> 
> Hence, my motivation for only publishing Javadoc HTMLs for `log4j-api` and
> `log4j-core`, which contain sufficient support material in the manual *and*
> Javadocs.
> 
> Nevertheless, if you still disagree, I would be more than happy to hear
> your reasoning.
> 
> On Tue, Feb 14, 2023 at 5:58 PM Matt Sicker <m...@musigma.org> wrote:
> 
>> Can you also add the iostreams docs? Basically, the five listed on the top
>> of https://logging.apache.org/log4j/2.x/javadoc.html should still be
>> published, and when we get to 3.0, that will also need to include the
>> plugins module. It would be nice if we could publish javadoc jars for
>> everything, though I’m not sure if IDEs and such can figure out the
>> javadocs from the source jar itself.
>> 
>>> On Feb 12, 2023, at 3:06 PM, Volkan Yazıcı <vol...@yazi.ci> wrote:
>>> 
>>> Hello,
>>> 
>>> Javadocs were broken in `release-2.x`. That is, we were neither
>> generating
>>> Javadoc JARs deployed to Nexus, nor generating Javadoc HTMLs that are
>>> linked in our website. I have just pushed a fix
>>> <
>> https://github.com/apache/logging-log4j2/commit/8d720e722b42efc063b84989ca7b0984d451a041
>>> 
>>> improving the situation as follows:
>>> 
>>>  1. *Removed `maven-jxr-plugin`.* This was used to generate web pages of
>>>  the source code linked from CheckStyle reports and such. We are not
>>>  generating any reports (incl. the CheckStyle report!) using
>>>  `maven-site-plugin` anymore. Sources can still be displayed via GitHub.
>>>  2. *Removed Javadoc JARs* deployed to Nexus. We already publish source
>>>  JARs and that is what IDEs use to display Javadocs. I don't think
>> anybody
>>>  uses Javadoc JARs anymore.
>>>  3. *Generating Javadoc HTML only for the `log4j-api` and `log4j-core`*
>>>  modules.
>>>  4. Created #1275 <https://github.com/apache/logging-log4j2/issues/1275
>>> 
>>>  so that we can ensure nobody lands any commits breaking the Javadocs
>>>  anymore.
>>> 
>>> Please let me know if you have any objections.
>> 
>> 

Reply via email to