Javadoc with v8 doclet

[Remko Popma]

Matt has mentioned a few times that he wanted to use the Javadoc format produced by java 8, but the doclet is too strict.

This blog post may have a solution for that:
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

Sent from my iPhone

[Gary Gregory]

Nah, we should just fix our comments...

Gary

<div>-------- Original message --------</div><div>From: Remko Popma <***@gmail.com> </div><div>Date:09/20/2014 23:11 (GMT-05:00) </div><div>To: Developers List Log4J <log4j-***@logging.apache.org> </div><div>Subject: Javadoc with v8 doclet </div><div>
</div>Matt has mentioned a few times that he wanted to use the Javadoc format produced by java 8, but the doclet is too strict.

This blog post may have a solution for that:
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

Sent from my iPhone
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-***@logging.apache.org
For additional commands, e-mail: log4j-dev-***@logging.apache.org

[Remko Popma]

I was a bit shocked after reading the article.
The requirements are very strict.

If you ask me what would be a better use of my time: fix outstanding jiras
or add new features or make javadoc conform to some standard, I think out
of those three, javadoc would benefit our users least...

(I don't object to writing new javadoc according to the stricter rules, it
just seems like a bit of a waste of time to fix the old docs.)

And if we can get the benefit of the nicer looking javadoc HTML without
paying the price of spending our valuable time to reformat etc, I'd say go
for it!

Post by Gary Gregory
Nah, we should just fix our comments...
Gary
-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet
Matt has mentioned a few times that he wanted to use the Javadoc format
produced by java 8, but the doclet is too strict.
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
Sent from my iPhone
---------------------------------------------------------------------

[Ralph Goers]

I have to disagree. The fact that it doesn’t allow <br /> and also doesn’t allow <br></br> is a showstopper as far as I am concerned. I always use closing tags and am not going to change just because doclint doesn’t allow it.

My vote is to disable doclint and move on.

Ralph

Post by Gary Gregory
Nah, we should just fix our comments...
Gary
-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet
Matt has mentioned a few times that he wanted to use the Javadoc format produced by java 8, but the doclet is too strict.
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
Sent from my iPhone
---------------------------------------------------------------------

[Matt Sicker]

If we can just build it with the (perfectly valid HTML5) invalid HTML by
disabling something, that would be ideal.

I have to disagree. The fact that it doesn’t allow <br /> and also
doesn’t allow <br></br> is a showstopper as far as I am concerned. I
always use closing tags and am not going to change just because doclint
doesn’t allow it.
My vote is to disable doclint and move on.
Ralph

Post by Gary Gregory
Nah, we should just fix our comments...
Gary
-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet
Matt has mentioned a few times that he wanted to use the Javadoc format

produced by java 8, but the doclet is too strict.

Post by Gary Gregory
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
Sent from my iPhone
---------------------------------------------------------------------

---------------------------------------------------------------------

[Remko Popma]

If I understand correctly, the article offers a way to do that.

Sent from my iPhone

If we can just build it with the (perfectly valid HTML5) invalid HTML by disabling something, that would be ideal.

I have to disagree. The fact that it doesnft allow <br /> and also doesnft allow <br></br> is a showstopper as far as I am concerned. I always use closing tags and am not going to change just because doclint doesnft allow it.
My vote is to disable doclint and move on.
Ralph

Post by Gary Gregory
Nah, we should just fix our comments...
Gary
-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet
Matt has mentioned a few times that he wanted to use the Javadoc format produced by java 8, but the doclet is too strict.
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
Sent from my iPhone
---------------------------------------------------------------------

---------------------------------------------------------------------

--

[Gary Gregory]

Bah, at some point, that will be the new normal for everyone.

The best way to deal with this is to agree to build with Java 8 with compiler settings that generate java 6 byte codes which we already have.

If we all pitch in it won't take long.

Personally I do everything in Java 7 and I am migrating to 8 project by project. 

Gary

<div>-------- Original message --------</div><div>From: Remko Popma <***@gmail.com> </div><div>Date:09/21/2014 07:12 (GMT-05:00) </div><div>To: Log4J Developers List <log4j-***@logging.apache.org> </div><div>Subject: Re: Javadoc with v8 doclet </div><div>
</div>I was a bit shocked after reading the article.
The requirements are very strict.

If you ask me what would be a better use of my time: fix outstanding jiras or add new features or make javadoc conform to some standard, I think out of those three, javadoc would benefit our users least...

(I don't object to writing new javadoc according to the stricter rules, it just seems like a bit of a waste of time to fix the old docs.)

And if we can get the benefit of the nicer looking javadoc HTML without paying the price of spending our valuable time to reformat etc, I'd say go for it!


On Sun, Sep 21, 2014 at 7:49 PM, Gary Gregory <***@gmail.com> wrote:
Nah, we should just fix our comments...

Gary


-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet

Matt has mentioned a few times that he wanted to use the Javadoc format produced by java 8, but the doclet is too strict.

This blog post may have a solution for that:
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

Sent from my iPhone
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-dev-***@logging.apache.org
For additional commands, e-mail: log4j-dev-***@logging.apache.org

[Matt Sicker]

What I don't get is that the OpenJDK javadocs are still a mix of
never-touched 1.0 docs (which definitely uses the loose format), yet they
still manage to build it without fixing all their docs. There must be a way
to auto-fix everything.

Post by Gary Gregory
Bah, at some point, that will be the new normal for everyone.
The best way to deal with this is to agree to build with Java 8 with
compiler settings that generate java 6 byte codes which we already have.
If we all pitch in it won't take long.
Personally I do everything in Java 7 and I am migrating to 8 project by
project.
Gary
-------- Original message --------
From: Remko Popma
Date:09/21/2014 07:12 (GMT-05:00)
To: Log4J Developers List
Subject: Re: Javadoc with v8 doclet
I was a bit shocked after reading the article.
The requirements are very strict.
If you ask me what would be a better use of my time: fix outstanding jiras
or add new features or make javadoc conform to some standard, I think out
of those three, javadoc would benefit our users least...
(I don't object to writing new javadoc according to the stricter rules, it
just seems like a bit of a waste of time to fix the old docs.)
And if we can get the benefit of the nicer looking javadoc HTML without
paying the price of spending our valuable time to reformat etc, I'd say go
for it!

Post by Gary Gregory
Nah, we should just fix our comments...
Gary
-------- Original message --------
From: Remko Popma
Date:09/20/2014 23:11 (GMT-05:00)
To: Developers List Log4J
Subject: Javadoc with v8 doclet
Matt has mentioned a few times that he wanted to use the Javadoc format
produced by java 8, but the doclet is too strict.
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
Sent from my iPhone
---------------------------------------------------------------------