You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by "Gary D. Gregory" <gg...@apache.org> on 2024/10/14 19:29:20 UTC
[CLI] Javadoc
Hi All,
We now have append methods like:
public interface HelpAppendable extends Appendable {
/**
* Appends a header.
*
* @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
* @param text the text for the header
* @throws IOException on write failure
*/
void appendHeader(int level, CharSequence text) throws IOException;
...
The supertype defines behavior for null input, but here we do not, we should either document it as:
- Same as the super type, same kind of Javadoc
- Explicitly document that it is up to the implementing class
Thoughts?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by Johannes Weberhofer <jw...@weberhofer.at>.
We had a discussion about the same thing a few month ago - I personally
like this kind of annotations a lot. I found a very interesting project
at https://jspecify.dev/
A good overview mentioning several implementations at
https://stackoverflow.com/questions/4963300/which-notnull-java-annotation-should-i-use
Johannes
Am 16.10.24 um 17:14 schrieb Gary Gregory:
> I don't think we need this, mostly because I prefer to not have issues with
> annotation X vs. Y vs. Z. There are a ton of these types of annotations out
> there and using one vs another because the Jetbrain IDE likes it is not a
> good enough reason IMO. There's also a javax version, and a jakarta
> version, and so on. Then there is the retention issue, and which one to
> pick and why, which then brings you to who really is the client for these,
> the source maintainer? The IDE tooling? A runtime framework? I'd rather
> skip all of it until it becomes a requirement.
>
> Gary
>
> On Wed, Oct 16, 2024, 9:50 AM Claude Warren <cl...@xenei.com> wrote:
>
>> What is the general stance on commons to import the annotations? Is there
>> a reason not to? I'm happy to make the changes but want to make sure there
>> is not a blocker first.
>>
>> Claude
>>
>> On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
>>
>>> yep, I always think, this kind of allow null not allow null things shall
>> be
>>> marked not by doc, but by annotations.
>>>
>>> Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
>>>
>>>> 1. important jetbrains annotations as maven dependency.
>>>> 2.add @Nullable in parent class's param
>>>> 3.add @NotNull at child class param
>>>>
>>>> ------------------------------
>>>> *From:* Gary D. Gregory <gg...@apache.org>
>>>> *Sent:* Tuesday, October 15, 2024 3:29:20 AM
>>>> *To:* dev@commons.apache.org <de...@commons.apache.org>
>>>> *Subject:* [CLI] Javadoc
>>>>
>>>> Hi All,
>>>>
>>>> We now have append methods like:
>>>>
>>>> public interface HelpAppendable extends Appendable {
>>>>
>>>> /**
>>>> * Appends a header.
>>>> *
>>>> * @param level the level of the header. This is equivalent to the
>>>> "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
>>>> * @param text the text for the header
>>>> * @throws IOException on write failure
>>>> */
>>>> void appendHeader(int level, CharSequence text) throws IOException;
>>>>
>>>> ...
>>>>
>>>> The supertype defines behavior for null input, but here we do not, we
>>>> should either document it as:
>>>> - Same as the super type, same kind of Javadoc
>>>> - Explicitly document that it is up to the implementing class
>>>>
>>>> Thoughts?
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>
>>>>
>>
>> --
>> LinkedIn: http://www.linkedin.com/in/claudewarren
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by Gary Gregory <ga...@gmail.com>.
Let's get back on topic here please: What I'm looking for is what the
JAVADOC should say, in words, to set expectations for users/call sites and
provide guidance for implementors.
What matters more is what null means when it's allowed because telling me
something is nullable with an annotation is useless without an explainer
IMO.
Gary
Gary
On Wed, Oct 16, 2024, 12:27 PM sebb <se...@gmail.com> wrote:
> On Wed, 16 Oct 2024 at 16:15, Gary Gregory <ga...@gmail.com> wrote:
> >
> > I don't think we need this, mostly because I prefer to not have issues
> with
> > annotation X vs. Y vs. Z. There are a ton of these types of annotations
> out
> > there and using one vs another because the Jetbrain IDE likes it is not a
> > good enough reason IMO. There's also a javax version, and a jakarta
> > version, and so on. Then there is the retention issue, and which one to
> > pick and why, which then brings you to who really is the client for
> these,
> > the source maintainer? The IDE tooling? A runtime framework? I'd rather
> > skip all of it until it becomes a requirement.
>
> Agreed.
>
> We certainly don't want annotations that create a runtime dependency.
>
> > Gary
> >
> > On Wed, Oct 16, 2024, 9:50 AM Claude Warren <cl...@xenei.com> wrote:
> >
> > > What is the general stance on commons to import the annotations? Is
> there
> > > a reason not to? I'm happy to make the changes but want to make sure
> there
> > > is not a blocker first.
> > >
> > > Claude
> > >
> > > On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com>
> wrote:
> > >
> > > > yep, I always think, this kind of allow null not allow null things
> shall
> > > be
> > > > marked not by doc, but by annotations.
> > > >
> > > > Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> > > >
> > > > > 1. important jetbrains annotations as maven dependency.
> > > > > 2.add @Nullable in parent class's param
> > > > > 3.add @NotNull at child class param
> > > > >
> > > > > ------------------------------
> > > > > *From:* Gary D. Gregory <gg...@apache.org>
> > > > > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > > > > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > > > > *Subject:* [CLI] Javadoc
> > > > >
> > > > > Hi All,
> > > > >
> > > > > We now have append methods like:
> > > > >
> > > > > public interface HelpAppendable extends Appendable {
> > > > >
> > > > > /**
> > > > > * Appends a header.
> > > > > *
> > > > > * @param level the level of the header. This is equivalent to
> the
> > > > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > > > * @param text the text for the header
> > > > > * @throws IOException on write failure
> > > > > */
> > > > > void appendHeader(int level, CharSequence text) throws
> IOException;
> > > > >
> > > > > ...
> > > > >
> > > > > The supertype defines behavior for null input, but here we do not,
> we
> > > > > should either document it as:
> > > > > - Same as the super type, same kind of Javadoc
> > > > > - Explicitly document that it is up to the implementing class
> > > > >
> > > > > Thoughts?
> > > > >
> > > > >
> ---------------------------------------------------------------------
> > > > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > > For additional commands, e-mail: dev-help@commons.apache.org
> > > > >
> > > > >
> > > >
> > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [CLI] Javadoc
Posted by sebb <se...@gmail.com>.
On Wed, 16 Oct 2024 at 16:15, Gary Gregory <ga...@gmail.com> wrote:
>
> I don't think we need this, mostly because I prefer to not have issues with
> annotation X vs. Y vs. Z. There are a ton of these types of annotations out
> there and using one vs another because the Jetbrain IDE likes it is not a
> good enough reason IMO. There's also a javax version, and a jakarta
> version, and so on. Then there is the retention issue, and which one to
> pick and why, which then brings you to who really is the client for these,
> the source maintainer? The IDE tooling? A runtime framework? I'd rather
> skip all of it until it becomes a requirement.
Agreed.
We certainly don't want annotations that create a runtime dependency.
> Gary
>
> On Wed, Oct 16, 2024, 9:50 AM Claude Warren <cl...@xenei.com> wrote:
>
> > What is the general stance on commons to import the annotations? Is there
> > a reason not to? I'm happy to make the changes but want to make sure there
> > is not a blocker first.
> >
> > Claude
> >
> > On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
> >
> > > yep, I always think, this kind of allow null not allow null things shall
> > be
> > > marked not by doc, but by annotations.
> > >
> > > Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> > >
> > > > 1. important jetbrains annotations as maven dependency.
> > > > 2.add @Nullable in parent class's param
> > > > 3.add @NotNull at child class param
> > > >
> > > > ------------------------------
> > > > *From:* Gary D. Gregory <gg...@apache.org>
> > > > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > > > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > > > *Subject:* [CLI] Javadoc
> > > >
> > > > Hi All,
> > > >
> > > > We now have append methods like:
> > > >
> > > > public interface HelpAppendable extends Appendable {
> > > >
> > > > /**
> > > > * Appends a header.
> > > > *
> > > > * @param level the level of the header. This is equivalent to the
> > > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > > * @param text the text for the header
> > > > * @throws IOException on write failure
> > > > */
> > > > void appendHeader(int level, CharSequence text) throws IOException;
> > > >
> > > > ...
> > > >
> > > > The supertype defines behavior for null input, but here we do not, we
> > > > should either document it as:
> > > > - Same as the super type, same kind of Javadoc
> > > > - Explicitly document that it is up to the implementing class
> > > >
> > > > Thoughts?
> > > >
> > > > ---------------------------------------------------------------------
> > > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > For additional commands, e-mail: dev-help@commons.apache.org
> > > >
> > > >
> > >
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by Gary Gregory <ga...@gmail.com>.
I don't think we need this, mostly because I prefer to not have issues with
annotation X vs. Y vs. Z. There are a ton of these types of annotations out
there and using one vs another because the Jetbrain IDE likes it is not a
good enough reason IMO. There's also a javax version, and a jakarta
version, and so on. Then there is the retention issue, and which one to
pick and why, which then brings you to who really is the client for these,
the source maintainer? The IDE tooling? A runtime framework? I'd rather
skip all of it until it becomes a requirement.
Gary
On Wed, Oct 16, 2024, 9:50 AM Claude Warren <cl...@xenei.com> wrote:
> What is the general stance on commons to import the annotations? Is there
> a reason not to? I'm happy to make the changes but want to make sure there
> is not a blocker first.
>
> Claude
>
> On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
>
> > yep, I always think, this kind of allow null not allow null things shall
> be
> > marked not by doc, but by annotations.
> >
> > Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> >
> > > 1. important jetbrains annotations as maven dependency.
> > > 2.add @Nullable in parent class's param
> > > 3.add @NotNull at child class param
> > >
> > > ------------------------------
> > > *From:* Gary D. Gregory <gg...@apache.org>
> > > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > > *Subject:* [CLI] Javadoc
> > >
> > > Hi All,
> > >
> > > We now have append methods like:
> > >
> > > public interface HelpAppendable extends Appendable {
> > >
> > > /**
> > > * Appends a header.
> > > *
> > > * @param level the level of the header. This is equivalent to the
> > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > * @param text the text for the header
> > > * @throws IOException on write failure
> > > */
> > > void appendHeader(int level, CharSequence text) throws IOException;
> > >
> > > ...
> > >
> > > The supertype defines behavior for null input, but here we do not, we
> > > should either document it as:
> > > - Same as the super type, same kind of Javadoc
> > > - Explicitly document that it is up to the implementing class
> > >
> > > Thoughts?
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> >
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] Javadoc
Posted by Claude Warren <cl...@xenei.com>.
Yeah, it was the dependency question. I know that in general commons
projects try to keep dependencies to a minimum. I like the idea and think
I would agree with you after playing with the annotations.
On Wed, Oct 16, 2024 at 3:17 PM Xeno Amess <xe...@gmail.com> wrote:
> apply jsr 305 annotations just make codes neat (IMO)
> also good for quite some ide/analyzing tools when they try index/auto find
> bugs.
> well there be very many jsr-305 impls so if not jetbrains we can use google
> code or even impl our own one.
> negative point is we need another dependency(though usually a very small
> size one.)
>
> Claude Warren <cl...@xenei.com> 于2024年10月16日周三 21:49写道：
>
> > What is the general stance on commons to import the annotations? Is
> there
> > a reason not to? I'm happy to make the changes but want to make sure
> there
> > is not a blocker first.
> >
> > Claude
> >
> > On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
> >
> > > yep, I always think, this kind of allow null not allow null things
> shall
> > be
> > > marked not by doc, but by annotations.
> > >
> > > Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> > >
> > > > 1. important jetbrains annotations as maven dependency.
> > > > 2.add @Nullable in parent class's param
> > > > 3.add @NotNull at child class param
> > > >
> > > > ------------------------------
> > > > *From:* Gary D. Gregory <gg...@apache.org>
> > > > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > > > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > > > *Subject:* [CLI] Javadoc
> > > >
> > > > Hi All,
> > > >
> > > > We now have append methods like:
> > > >
> > > > public interface HelpAppendable extends Appendable {
> > > >
> > > > /**
> > > > * Appends a header.
> > > > *
> > > > * @param level the level of the header. This is equivalent to
> the
> > > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > > * @param text the text for the header
> > > > * @throws IOException on write failure
> > > > */
> > > > void appendHeader(int level, CharSequence text) throws
> IOException;
> > > >
> > > > ...
> > > >
> > > > The supertype defines behavior for null input, but here we do not, we
> > > > should either document it as:
> > > > - Same as the super type, same kind of Javadoc
> > > > - Explicitly document that it is up to the implementing class
> > > >
> > > > Thoughts?
> > > >
> > > > ---------------------------------------------------------------------
> > > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > For additional commands, e-mail: dev-help@commons.apache.org
> > > >
> > > >
> > >
> >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] Javadoc
Posted by Xeno Amess <xe...@gmail.com>.
apply jsr 305 annotations just make codes neat (IMO)
also good for quite some ide/analyzing tools when they try index/auto find
bugs.
well there be very many jsr-305 impls so if not jetbrains we can use google
code or even impl our own one.
negative point is we need another dependency(though usually a very small
size one.)
Claude Warren <cl...@xenei.com> 于2024年10月16日周三 21:49写道：
> What is the general stance on commons to import the annotations? Is there
> a reason not to? I'm happy to make the changes but want to make sure there
> is not a blocker first.
>
> Claude
>
> On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
>
> > yep, I always think, this kind of allow null not allow null things shall
> be
> > marked not by doc, but by annotations.
> >
> > Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> >
> > > 1. important jetbrains annotations as maven dependency.
> > > 2.add @Nullable in parent class's param
> > > 3.add @NotNull at child class param
> > >
> > > ------------------------------
> > > *From:* Gary D. Gregory <gg...@apache.org>
> > > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > > *Subject:* [CLI] Javadoc
> > >
> > > Hi All,
> > >
> > > We now have append methods like:
> > >
> > > public interface HelpAppendable extends Appendable {
> > >
> > > /**
> > > * Appends a header.
> > > *
> > > * @param level the level of the header. This is equivalent to the
> > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > * @param text the text for the header
> > > * @throws IOException on write failure
> > > */
> > > void appendHeader(int level, CharSequence text) throws IOException;
> > >
> > > ...
> > >
> > > The supertype defines behavior for null input, but here we do not, we
> > > should either document it as:
> > > - Same as the super type, same kind of Javadoc
> > > - Explicitly document that it is up to the implementing class
> > >
> > > Thoughts?
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> >
>
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
Re: [CLI] Javadoc
Posted by Claude Warren <cl...@xenei.com>.
What is the general stance on commons to import the annotations? Is there
a reason not to? I'm happy to make the changes but want to make sure there
is not a blocker first.
Claude
On Tue, Oct 15, 2024 at 9:56 AM Xeno Amess <xe...@gmail.com> wrote:
> yep, I always think, this kind of allow null not allow null things shall be
> marked not by doc, but by annotations.
>
> Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
>
> > 1. important jetbrains annotations as maven dependency.
> > 2.add @Nullable in parent class's param
> > 3.add @NotNull at child class param
> >
> > ------------------------------
> > *From:* Gary D. Gregory <gg...@apache.org>
> > *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> > *To:* dev@commons.apache.org <de...@commons.apache.org>
> > *Subject:* [CLI] Javadoc
> >
> > Hi All,
> >
> > We now have append methods like:
> >
> > public interface HelpAppendable extends Appendable {
> >
> > /**
> > * Appends a header.
> > *
> > * @param level the level of the header. This is equivalent to the
> > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > * @param text the text for the header
> > * @throws IOException on write failure
> > */
> > void appendHeader(int level, CharSequence text) throws IOException;
> >
> > ...
> >
> > The supertype defines behavior for null input, but here we do not, we
> > should either document it as:
> > - Same as the super type, same kind of Javadoc
> > - Explicitly document that it is up to the implementing class
> >
> > Thoughts?
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] Javadoc
Posted by Xeno Amess <xe...@gmail.com>.
yep, I always think, this kind of allow null not allow null things shall be
marked not by doc, but by annotations.
Xeno Amess <xe...@gmail.com> 于2024年10月15日周二 04:10写道：
> 1. important jetbrains annotations as maven dependency.
> 2.add @Nullable in parent class's param
> 3.add @NotNull at child class param
>
> ------------------------------
> *From:* Gary D. Gregory <gg...@apache.org>
> *Sent:* Tuesday, October 15, 2024 3:29:20 AM
> *To:* dev@commons.apache.org <de...@commons.apache.org>
> *Subject:* [CLI] Javadoc
>
> Hi All,
>
> We now have append methods like:
>
> public interface HelpAppendable extends Appendable {
>
> /**
> * Appends a header.
> *
> * @param level the level of the header. This is equivalent to the
> "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> * @param text the text for the header
> * @throws IOException on write failure
> */
> void appendHeader(int level, CharSequence text) throws IOException;
>
> ...
>
> The supertype defines behavior for null input, but here we do not, we
> should either document it as:
> - Same as the super type, same kind of Javadoc
> - Explicitly document that it is up to the implementing class
>
> Thoughts?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [CLI] Javadoc
Posted by Xeno Amess <xe...@gmail.com>.
1. important jetbrains annotations as maven dependency.
2.add @Nullable in parent class's param
3.add @NotNull at child class param
________________________________
From: Gary D. Gregory <gg...@apache.org>
Sent: Tuesday, October 15, 2024 3:29:20 AM
To: dev@commons.apache.org <de...@commons.apache.org>
Subject: [CLI] Javadoc
Hi All,
We now have append methods like:
public interface HelpAppendable extends Appendable {
/**
* Appends a header.
*
* @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
* @param text the text for the header
* @throws IOException on write failure
*/
void appendHeader(int level, CharSequence text) throws IOException;
...
The supertype defines behavior for null input, but here we do not, we should either document it as:
- Same as the super type, same kind of Javadoc
- Explicitly document that it is up to the implementing class
Thoughts?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by "Gary D. Gregory" <gg...@apache.org>.
Hi Claude,
I just did after seeing your message, instead of going round and round ;)
Gary
On 2024/10/19 10:22:28 Claude Warren wrote:
> Gary,
>
> I went looking for the javadoc in question but did not find it. Did you
> already clean it up? If so, thanks. If not can you point to the issue?
>
> Thank you,
> Claude
>
> On Thu, Oct 17, 2024 at 3:08 PM Gary D. Gregory <gg...@apache.org> wrote:
>
> > Note that the Javadoc for org.apache.commons.cli.help.HelpFormatter use
> > deprecated code. Please update it or I can do it later.
> >
> > Gary
> >
> > On 2024/10/17 13:39:53 Claude Warren wrote:
> > > I think that all of the HelpAppendable methods expect that if null or
> > empty
> > > string is passed then nothing is output. In addition, for the list case
> > an
> > > empty list results in no output.
> > >
> > > I will update the documentation.
> > >
> > > On Thu, Oct 17, 2024 at 10:20 AM Arnout Engelen <en...@apache.org>
> > wrote:
> > >
> > > > On Mon, Oct 14, 2024 at 9:29 PM Gary D. Gregory <gg...@apache.org>
> > > > wrote:
> > > > >
> > > > > Hi All,
> > > > >
> > > > > We now have append methods like:
> > > > >
> > > > > public interface HelpAppendable extends Appendable {
> > > > >
> > > > > /**
> > > > > * Appends a header.
> > > > > *
> > > > > * @param level the level of the header. This is equivalent to
> > the
> > > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > > > * @param text the text for the header
> > > > > * @throws IOException on write failure
> > > > > */
> > > > > void appendHeader(int level, CharSequence text) throws
> > IOException;
> > > > >
> > > > > ...
> > > > >
> > > > > The supertype defines behavior for null input, but here we do not, we
> > > > should either document it as:
> > > > > - Same as the super type, same kind of Javadoc
> > > > > - Explicitly document that it is up to the implementing class
> > > > >
> > > > > Thoughts?
> > > >
> > > > While for the general 'append' I can see the motivation for outputting
> > > > 'null' for null input. For headers it seems simply invalid to me, and
> > > > IMO it'd make more sense to declare all implementations should throw a
> > > > NullPointerException in that case.
> > > >
> > > > If we do decide to allow null here, I think we should define the
> > > > behavior in a way that all implementations can follow - which the
> > > > super type does nicely ('If csq is null, then characters will be
> > > > appended as if csq contained the four characters "null".'). I don't
> > > > see a strong reason to leave it up to the implementing class - what
> > > > would be the use case?
> > > >
> > > >
> > > > Kind regards,
> > > >
> > > > --
> > > > Arnout Engelen
> > > > ASF Security Response
> > > > Apache Pekko PMC member, ASF Member
> > > > NixOS Committer
> > > > Independent Open Source consultant
> > > >
> > > > ---------------------------------------------------------------------
> > > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > > For additional commands, e-mail: dev-help@commons.apache.org
> > > >
> > > >
> > >
> > > --
> > > LinkedIn: http://www.linkedin.com/in/claudewarren
> > >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by Claude Warren <cl...@xenei.com>.
Gary,
I went looking for the javadoc in question but did not find it. Did you
already clean it up? If so, thanks. If not can you point to the issue?
Thank you,
Claude
On Thu, Oct 17, 2024 at 3:08 PM Gary D. Gregory <gg...@apache.org> wrote:
> Note that the Javadoc for org.apache.commons.cli.help.HelpFormatter use
> deprecated code. Please update it or I can do it later.
>
> Gary
>
> On 2024/10/17 13:39:53 Claude Warren wrote:
> > I think that all of the HelpAppendable methods expect that if null or
> empty
> > string is passed then nothing is output. In addition, for the list case
> an
> > empty list results in no output.
> >
> > I will update the documentation.
> >
> > On Thu, Oct 17, 2024 at 10:20 AM Arnout Engelen <en...@apache.org>
> wrote:
> >
> > > On Mon, Oct 14, 2024 at 9:29 PM Gary D. Gregory <gg...@apache.org>
> > > wrote:
> > > >
> > > > Hi All,
> > > >
> > > > We now have append methods like:
> > > >
> > > > public interface HelpAppendable extends Appendable {
> > > >
> > > > /**
> > > > * Appends a header.
> > > > *
> > > > * @param level the level of the header. This is equivalent to
> the
> > > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > > * @param text the text for the header
> > > > * @throws IOException on write failure
> > > > */
> > > > void appendHeader(int level, CharSequence text) throws
> IOException;
> > > >
> > > > ...
> > > >
> > > > The supertype defines behavior for null input, but here we do not, we
> > > should either document it as:
> > > > - Same as the super type, same kind of Javadoc
> > > > - Explicitly document that it is up to the implementing class
> > > >
> > > > Thoughts?
> > >
> > > While for the general 'append' I can see the motivation for outputting
> > > 'null' for null input. For headers it seems simply invalid to me, and
> > > IMO it'd make more sense to declare all implementations should throw a
> > > NullPointerException in that case.
> > >
> > > If we do decide to allow null here, I think we should define the
> > > behavior in a way that all implementations can follow - which the
> > > super type does nicely ('If csq is null, then characters will be
> > > appended as if csq contained the four characters "null".'). I don't
> > > see a strong reason to leave it up to the implementing class - what
> > > would be the use case?
> > >
> > >
> > > Kind regards,
> > >
> > > --
> > > Arnout Engelen
> > > ASF Security Response
> > > Apache Pekko PMC member, ASF Member
> > > NixOS Committer
> > > Independent Open Source consultant
> > >
> > > ---------------------------------------------------------------------
> > > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > > For additional commands, e-mail: dev-help@commons.apache.org
> > >
> > >
> >
> > --
> > LinkedIn: http://www.linkedin.com/in/claudewarren
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] Javadoc
Posted by "Gary D. Gregory" <gg...@apache.org>.
Note that the Javadoc for org.apache.commons.cli.help.HelpFormatter use deprecated code. Please update it or I can do it later.
Gary
On 2024/10/17 13:39:53 Claude Warren wrote:
> I think that all of the HelpAppendable methods expect that if null or empty
> string is passed then nothing is output. In addition, for the list case an
> empty list results in no output.
>
> I will update the documentation.
>
> On Thu, Oct 17, 2024 at 10:20 AM Arnout Engelen <en...@apache.org> wrote:
>
> > On Mon, Oct 14, 2024 at 9:29 PM Gary D. Gregory <gg...@apache.org>
> > wrote:
> > >
> > > Hi All,
> > >
> > > We now have append methods like:
> > >
> > > public interface HelpAppendable extends Appendable {
> > >
> > > /**
> > > * Appends a header.
> > > *
> > > * @param level the level of the header. This is equivalent to the
> > "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > > * @param text the text for the header
> > > * @throws IOException on write failure
> > > */
> > > void appendHeader(int level, CharSequence text) throws IOException;
> > >
> > > ...
> > >
> > > The supertype defines behavior for null input, but here we do not, we
> > should either document it as:
> > > - Same as the super type, same kind of Javadoc
> > > - Explicitly document that it is up to the implementing class
> > >
> > > Thoughts?
> >
> > While for the general 'append' I can see the motivation for outputting
> > 'null' for null input. For headers it seems simply invalid to me, and
> > IMO it'd make more sense to declare all implementations should throw a
> > NullPointerException in that case.
> >
> > If we do decide to allow null here, I think we should define the
> > behavior in a way that all implementations can follow - which the
> > super type does nicely ('If csq is null, then characters will be
> > appended as if csq contained the four characters "null".'). I don't
> > see a strong reason to leave it up to the implementing class - what
> > would be the use case?
> >
> >
> > Kind regards,
> >
> > --
> > Arnout Engelen
> > ASF Security Response
> > Apache Pekko PMC member, ASF Member
> > NixOS Committer
> > Independent Open Source consultant
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>
> --
> LinkedIn: http://www.linkedin.com/in/claudewarren
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [CLI] Javadoc
Posted by Claude Warren <cl...@xenei.com>.
I think that all of the HelpAppendable methods expect that if null or empty
string is passed then nothing is output. In addition, for the list case an
empty list results in no output.
I will update the documentation.
On Thu, Oct 17, 2024 at 10:20 AM Arnout Engelen <en...@apache.org> wrote:
> On Mon, Oct 14, 2024 at 9:29 PM Gary D. Gregory <gg...@apache.org>
> wrote:
> >
> > Hi All,
> >
> > We now have append methods like:
> >
> > public interface HelpAppendable extends Appendable {
> >
> > /**
> > * Appends a header.
> > *
> > * @param level the level of the header. This is equivalent to the
> "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> > * @param text the text for the header
> > * @throws IOException on write failure
> > */
> > void appendHeader(int level, CharSequence text) throws IOException;
> >
> > ...
> >
> > The supertype defines behavior for null input, but here we do not, we
> should either document it as:
> > - Same as the super type, same kind of Javadoc
> > - Explicitly document that it is up to the implementing class
> >
> > Thoughts?
>
> While for the general 'append' I can see the motivation for outputting
> 'null' for null input. For headers it seems simply invalid to me, and
> IMO it'd make more sense to declare all implementations should throw a
> NullPointerException in that case.
>
> If we do decide to allow null here, I think we should define the
> behavior in a way that all implementations can follow - which the
> super type does nicely ('If csq is null, then characters will be
> appended as if csq contained the four characters "null".'). I don't
> see a strong reason to leave it up to the implementing class - what
> would be the use case?
>
>
> Kind regards,
>
> --
> Arnout Engelen
> ASF Security Response
> Apache Pekko PMC member, ASF Member
> NixOS Committer
> Independent Open Source consultant
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
LinkedIn: http://www.linkedin.com/in/claudewarren
Re: [CLI] Javadoc
Posted by Arnout Engelen <en...@apache.org>.
On Mon, Oct 14, 2024 at 9:29 PM Gary D. Gregory <gg...@apache.org> wrote:
>
> Hi All,
>
> We now have append methods like:
>
> public interface HelpAppendable extends Appendable {
>
> /**
> * Appends a header.
> *
> * @param level the level of the header. This is equivalent to the "1", "2", or "3" in the HTML "h1", "h2", "h3" tags.
> * @param text the text for the header
> * @throws IOException on write failure
> */
> void appendHeader(int level, CharSequence text) throws IOException;
>
> ...
>
> The supertype defines behavior for null input, but here we do not, we should either document it as:
> - Same as the super type, same kind of Javadoc
> - Explicitly document that it is up to the implementing class
>
> Thoughts?
While for the general 'append' I can see the motivation for outputting
'null' for null input. For headers it seems simply invalid to me, and
IMO it'd make more sense to declare all implementations should throw a
NullPointerException in that case.
If we do decide to allow null here, I think we should define the
behavior in a way that all implementations can follow - which the
super type does nicely ('If csq is null, then characters will be
appended as if csq contained the four characters "null".'). I don't
see a strong reason to leave it up to the implementing class - what
would be the use case?
Kind regards,
--
Arnout Engelen
ASF Security Response
Apache Pekko PMC member, ASF Member
NixOS Committer
Independent Open Source consultant
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org