[jira] [Comment Edited] (LOG4J2-2982) Use {@systemProperty} javadoc tag

["Marcono1234 (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/LOG4J2-2982?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17255319#comment-17255319 ] 

Marcono1234 edited comment on LOG4J2-2982 at 12/27/20, 8:53 PM:
----------------------------------------------------------------

Sorry, when I locally built Log4j2 I saw that you are already using Maven toolchains and assumed you are using a newer {{javadoc}} version already, but it turns out that is not the case.

However, thanks to Maven toolchains and toolchain support by the Maven javadoc plugin, it appears it is not that difficult to use a newer {{javadoc}} version. I have written a proof of concept here: https://github.com/Marcono1234/logging-log4j2/tree/marcono1234/javadoc-upgrade (likely incomplete and unstable!)
It only requires you to have a JDK 15 in your Maven toolchain. I have not run a full {{mvn clean install}}, but the following seems to work fine:
{code}
mvn clean site -DskipTests --projects log4j-api
{code}
And you will notice that the javadoc has all the latest features, most notably the search bar in the top right corner. Yet it is still created for Java 8 and has the external links to JDK 8.

Due to [JDK-8248010|https://bugs.openjdk.java.net/browse/JDK-8248010] some external links might be slightly incorrect, however on the other hand [JDK-8144118|https://bugs.openjdk.java.net/browse/JDK-8144118] already caused the same issue in the past.
Though, maybe it would be worth waiting for JDK 16 due to [JDK-8249133|https://bugs.openjdk.java.net/browse/JDK-8249133] which is quite annyoing in my opinion.

----
{quote}
Yeah - that isn't likely. 
{quote}
So does this still stand?


was (Author: marcono1234):
Sorry, when I locally built Log4j2 I saw that you are already using Maven toolchains and assumed you are using a newer {{javadoc}} version already, but it turns out that is not the case.

However, thanks to Maven toolchains and toolchain support by the Maven javadoc plugin, it appears it is not that difficult to use a newer {{javadoc}} version. I have written a proof of concept here: https://github.com/Marcono1234/logging-log4j2/tree/marcono1234/javadoc-upgrade (likely incomplete and unstable!)
It only requires you to have a JDK 15 in your Maven toolchain. I have not run a full {{mvn clean install}}, but the following seems to work fine:
{code}
mvn clean site "-DskipTests" --projects log4j-api
{code}
And you will notice that the javadoc has all the latest features, most notably the search bar in the top right corner. Yet it is still created for Java 8 and has the external links to JDK 8.

Due to [JDK-8248010|https://bugs.openjdk.java.net/browse/JDK-8248010] some external links might be slightly incorrect, however on the other hand [JDK-8144118|https://bugs.openjdk.java.net/browse/JDK-8144118] already caused the same issue in the past.
Though, maybe it would be worth waiting for JDK 16 due to [JDK-8249133|https://bugs.openjdk.java.net/browse/JDK-8249133] which is quite annyoing in my opinion.

----
{quote}
Yeah - that isn't likely. 
{quote}
So does this still stand?

> Use {@systemProperty} javadoc tag
> ---------------------------------
>
>                 Key: LOG4J2-2982
>                 URL: https://issues.apache.org/jira/browse/LOG4J2-2982
>             Project: Log4j 2
>          Issue Type: Improvement
>            Reporter: Marcono1234
>            Priority: Minor
>
> [JDK-8211132|https://bugs.openjdk.java.net/browse/JDK-8211132] added the [{{{@systemProperty ...\}}}|https://docs.oracle.com/en/java/javase/15/docs/specs/javadoc/doc-comment-spec.html#systemproperty] javadoc tag. This tag makes it easier to find System Properties.
> It would be good if the Log4j2 documentation used this tag since Log4j2 has quite a lot of System Properties.
> It might be necessary to adjust the Maven toolchain to upgrade the JDK for building the javadoc; in general it might be preferable to always use the latest JDK for building the javadoc because then the javadoc pages contain the latest improvements.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)