Re: [DISCUSSION] Shall we remove ant javadoc task?
To close this one. The patch to fix javadoc and enable in CI under the ant check the failure under broken javadoc is ready. After considering the current project status, we decided to delay committing it until 5.0 is feature complete and all bug CEPs are in. Best regards, Ekaterina On Mon, 21 Aug 2023 at 15:30, Miklosovic, Stefan < [email protected]> wrote: > You can play with this in > > File -> Settings -> Editor -> Inspections -> Javadoc > > HTML problems in Javadoc -> Severity: Error > > This will mark invalid html rendering of Javadocs as errorneous. > > There are other checkboxes as well. I am not saying it solves it all but > there is some room for tweaking this if one wishes. > > > From: Ekaterina Dimitrova > Sent: Monday, August 21, 2023 20:05 > To: [email protected] > Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > > NetApp Security WARNING: This is an external email. Do not click links or > open attachments unless you recognize the sender and know the content is > safe. > > > > My only slight concern is that almost all the errors fixed in > CASSANDRA-18717 are such that they don’t trigger error or warning in the > IDE. This means people will realize there is something to be done > differently around javadoc only after they run the check task. I figured > that before we commit to anything, it is good this point to be shared for > visibility. > Maxim highlighted for me that this is already the case with some of the > other checks we already have added with checkstyle. He looks into the > problem in CASSANDRA-18277, mentioning here in case there are committers > with cycles to help push it through > > On Thu, 17 Aug 2023 at 12:46, Mick Semb Wever [email protected]>> wrote: > +1 to `ant check` (and to failing on it). > > On Thu, 17 Aug 2023 at 18:43, Ekaterina Dimitrova <mailto:[email protected]>> wrote: > Agreed with Maxim. If we fail CI on the javadoc task, in my opinion it > should be added to ant check probably. > > On Thu, 17 Aug 2023 at 12:40, Maxim Muzafarov [email protected]>> wrote: > We have "artifacts" ant target that depends on "checks" and "gen-doc", > from my point of view, it would be nice to have the "artifacts" > depending on "javadocs" as well. That way we can be sure that > everything related is in good order. > > On Thu, 17 Aug 2023 at 18:05, Brandon Williams [email protected]>> wrote: > > > > If everything is good now, I think CI should fail if it regresses so > > we can keep it this way. > > > > Kind Regards, > > Brandon > > > > On Thu, Aug 17, 2023 at 10:49 AM Ekaterina Dimitrova > > mailto:[email protected]>> wrote: > > > > > > In CASSANDRA-18717 Maxim posted the javadoc fix. Stefan already made a > first pass of review so it seems we are not removing this ant task as it > was already fixed and there are people who find value of keeping it. > > > My question is do we want to fail CI if this regress or not? > > > > > > On Thu, 3 Aug 2023 at 22:44, Josh McKenzie <mailto:[email protected]>> wrote: > > >> > > >> the problem is that the javadoc task is not given the attention > > >> it deserves. The failonerror is currently 'false' and the task itself > > >> is not a part of any build and/or release processes > > >> > > >> > > >> I just wrote a tool that explores the distribution of keys across > multiple sstables, I needed some of the tools classes but not much more. > Javadocs would have made that easy > > >> > > >> You know what? I agree with all that. If I had to jump into the > source for the JDK or other libraries every time I needed to work with them > that'd be annoying. > > >> > > >> BTW, I have managed to fix all the javadoc errors. > > >> > > >> Of course you have. :) Industrious as usual Maxim; thanks for > tackling that! > > >> > > >> So yeah. Depending on how long javadocs take to generate, I think > having them as part of our pre-commit rotation makes sense. Could even add > them to our site with something like an "API" section (gasp) here: > https://cassandra.apache.org/doc/latest/< > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcassandra.apache.org%2Fdoc%2Flatest%2F&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7Cd3af424ebf634336d60108dba2715985%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638282379959793803%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAw
Re: [DISCUSSION] Shall we remove ant javadoc task?
You can play with this in File -> Settings -> Editor -> Inspections -> Javadoc HTML problems in Javadoc -> Severity: Error This will mark invalid html rendering of Javadocs as errorneous. There are other checkboxes as well. I am not saying it solves it all but there is some room for tweaking this if one wishes. From: Ekaterina Dimitrova Sent: Monday, August 21, 2023 20:05 To: [email protected] Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? NetApp Security WARNING: This is an external email. Do not click links or open attachments unless you recognize the sender and know the content is safe. My only slight concern is that almost all the errors fixed in CASSANDRA-18717 are such that they don’t trigger error or warning in the IDE. This means people will realize there is something to be done differently around javadoc only after they run the check task. I figured that before we commit to anything, it is good this point to be shared for visibility. Maxim highlighted for me that this is already the case with some of the other checks we already have added with checkstyle. He looks into the problem in CASSANDRA-18277, mentioning here in case there are committers with cycles to help push it through On Thu, 17 Aug 2023 at 12:46, Mick Semb Wever mailto:[email protected]>> wrote: +1 to `ant check` (and to failing on it). On Thu, 17 Aug 2023 at 18:43, Ekaterina Dimitrova mailto:[email protected]>> wrote: Agreed with Maxim. If we fail CI on the javadoc task, in my opinion it should be added to ant check probably. On Thu, 17 Aug 2023 at 12:40, Maxim Muzafarov mailto:[email protected]>> wrote: We have "artifacts" ant target that depends on "checks" and "gen-doc", from my point of view, it would be nice to have the "artifacts" depending on "javadocs" as well. That way we can be sure that everything related is in good order. On Thu, 17 Aug 2023 at 18:05, Brandon Williams mailto:[email protected]>> wrote: > > If everything is good now, I think CI should fail if it regresses so > we can keep it this way. > > Kind Regards, > Brandon > > On Thu, Aug 17, 2023 at 10:49 AM Ekaterina Dimitrova > mailto:[email protected]>> wrote: > > > > In CASSANDRA-18717 Maxim posted the javadoc fix. Stefan already made a > > first pass of review so it seems we are not removing this ant task as it > > was already fixed and there are people who find value of keeping it. > > My question is do we want to fail CI if this regress or not? > > > > On Thu, 3 Aug 2023 at 22:44, Josh McKenzie > > mailto:[email protected]>> wrote: > >> > >> the problem is that the javadoc task is not given the attention > >> it deserves. The failonerror is currently 'false' and the task itself > >> is not a part of any build and/or release processes > >> > >> > >> I just wrote a tool that explores the distribution of keys across multiple > >> sstables, I needed some of the tools classes but not much more. Javadocs > >> would have made that easy > >> > >> You know what? I agree with all that. If I had to jump into the source for > >> the JDK or other libraries every time I needed to work with them that'd be > >> annoying. > >> > >> BTW, I have managed to fix all the javadoc errors. > >> > >> Of course you have. :) Industrious as usual Maxim; thanks for tackling > >> that! > >> > >> So yeah. Depending on how long javadocs take to generate, I think having > >> them as part of our pre-commit rotation makes sense. Could even add them > >> to our site with something like an "API" section (gasp) here: > >> https://cassandra.apache.org/doc/latest/<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcassandra.apache.org%2Fdoc%2Flatest%2F&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7Cd3af424ebf634336d60108dba2715985%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638282379959793803%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=vwCuMFhF6J6pqcSarzALSTe3ACEaVwkCpcOtSZ5wX9k%3D&reserved=0>. > >> > >> Would certainly help motivate us to clarify the whole "what is an external > >> API we're committing to or not" discussions. > >> > >> On Thu, Aug 3, 2023, at 6:09 PM, Ekaterina Dimitrova wrote: > >> > >> Thank you Maxim. There is CASSANDRA-18717, I guess that patch should go > >> there. Keeping the task or not, the fix of the docs should go in anyway > >> IMHO.
Re: [DISCUSSION] Shall we remove ant javadoc task?
a/compare/trunk...Mmuzaf:cassandra:javadoc_build >>> > >> >>> > >> On Thu, 3 Aug 2023 at 21:20, Ekaterina Dimitrova < >>> [email protected]> wrote: >>> > >> > >>> > >> > Thank you Maxim, >>> > >> > >>> > >> > “ >>> > >> > >>> > >> > From my point of >>> > >> > view, the problem is that the javadoc task is not given the >>> attention >>> > >> > it deserves. The failonerror is currently 'false' and the task >>> itself >>> > >> > is not a part of any build and/or release processes, correct me >>> if I'm >>> > >> > wrong. >>> > >> > >>> > >> > So, >>> > >> > 1. Fix warnings/errors; >>> > >> > 2. Make the javadoc task part of the build (e.g. put it under >>> > >> > 'artifacts'), or make it part of the release process that is >>> regularly >>> > >> > checked on the CI; >>> > >> > 3. Publish/deploy the javadoc htmls for release in the special >>> > >> > directory of the cassandra website to give them a chance of being >>> > >> > indexed;“ >>> > >> > >>> > >> > This is aligned with what I saw and the two options mentioned at >>> the beginning - if we decide to keep it we should fix things and add the >>> task to CI, if we don’t because no one wants the html pages - then better >>> to remove it this ant task. >>> > >> > On your comment about 100 errors - it seems they are more. There >>> is a cap of 100 but when you fix them, more errors appear. >>> > >> > Further discussion can be found at CASSANDRA-17687 >>> > >> > >>> > >> > On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov >>> wrote: >>> > >> >> >>> > >> >> Personally, I find javadocs quite useful, especially when htmls >>> are >>> > >> >> indexed by search engines, which in turn increases the chances of >>> > >> >> finding the right answer faster (I have seen a lot of useful >>> javadocs >>> > >> >> in the source code). >>> > >> >> >>> > >> >> I have done a quick build of the javadocs: >>> > >> >> >>> > >> >> [javadoc] Building index for all the packages and classes... >>> > >> >> [javadoc] Building index for all classes... >>> > >> >> [javadoc] Building index for all classes... >>> > >> >> [javadoc] 100 errors >>> > >> >> [javadoc] 100 warnings >>> > >> >> >>> > >> >> 100 errors is no big deal and can be easily fixed. From my point >>> of >>> > >> >> view, the problem is that the javadoc task is not given the >>> attention >>> > >> >> it deserves. The failonerror is currently 'false' and the task >>> itself >>> > >> >> is not a part of any build and/or release processes, correct me >>> if I'm >>> > >> >> wrong. >>> > >> >> >>> > >> >> So, >>> > >> >> 1. Fix warnings/errors; >>> > >> >> 2. Make the javadoc task part of the build (e.g. put it under >>> > >> >> 'artifacts'), or make it part of the release process that is >>> regularly >>> > >> >> checked on the CI; >>> > >> >> 3. Publish/deploy the javadoc htmls for release in the special >>> > >> >> directory of the cassandra website to give them a chance of being >>> > >> >> indexed; >>> > >> >> >>> > >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan < >>> [email protected]> wrote: >>> > >> >> > >>> > >> >> > I don’t think anyone wants to remove the javadocs. This >>> thread is about removing the broken ant task which generates html files >>> from them. >>> > >> >> > >>> > >> >> > +1 from me on removing the ant task. If someone feels the >>> task is useful they can always implem
Re: [DISCUSSION] Shall we remove ant javadoc task?
x27;artifacts'), or make it part of the release process that is >> regularly >> > >> > checked on the CI; >> > >> > 3. Publish/deploy the javadoc htmls for release in the special >> > >> > directory of the cassandra website to give them a chance of being >> > >> > indexed;“ >> > >> > >> > >> > This is aligned with what I saw and the two options mentioned at >> the beginning - if we decide to keep it we should fix things and add the >> task to CI, if we don’t because no one wants the html pages - then better >> to remove it this ant task. >> > >> > On your comment about 100 errors - it seems they are more. There >> is a cap of 100 but when you fix them, more errors appear. >> > >> > Further discussion can be found at CASSANDRA-17687 >> > >> > >> > >> > On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov >> wrote: >> > >> >> >> > >> >> Personally, I find javadocs quite useful, especially when htmls >> are >> > >> >> indexed by search engines, which in turn increases the chances of >> > >> >> finding the right answer faster (I have seen a lot of useful >> javadocs >> > >> >> in the source code). >> > >> >> >> > >> >> I have done a quick build of the javadocs: >> > >> >> >> > >> >> [javadoc] Building index for all the packages and classes... >> > >> >> [javadoc] Building index for all classes... >> > >> >> [javadoc] Building index for all classes... >> > >> >> [javadoc] 100 errors >> > >> >> [javadoc] 100 warnings >> > >> >> >> > >> >> 100 errors is no big deal and can be easily fixed. From my point >> of >> > >> >> view, the problem is that the javadoc task is not given the >> attention >> > >> >> it deserves. The failonerror is currently 'false' and the task >> itself >> > >> >> is not a part of any build and/or release processes, correct me >> if I'm >> > >> >> wrong. >> > >> >> >> > >> >> So, >> > >> >> 1. Fix warnings/errors; >> > >> >> 2. Make the javadoc task part of the build (e.g. put it under >> > >> >> 'artifacts'), or make it part of the release process that is >> regularly >> > >> >> checked on the CI; >> > >> >> 3. Publish/deploy the javadoc htmls for release in the special >> > >> >> directory of the cassandra website to give them a chance of being >> > >> >> indexed; >> > >> >> >> > >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan < >> [email protected]> wrote: >> > >> >> > >> > >> >> > I don’t think anyone wants to remove the javadocs. This thread >> is about removing the broken ant task which generates html files from them. >> > >> >> > >> > >> >> > +1 from me on removing the ant task. If someone feels the task >> is useful they can always implement one that does not crash and add it back. >> > >> >> > >> > >> >> > -Jeremiah >> > >> >> > >> > >> >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" < >> [email protected]> wrote: >> > >> >> >> >> > >> >> >> I think that we can get more developers interested if there >> are available javadocs. While many of the core classes are not going to be >> touched by someone just starting, being able to understand what the >> external touch points are and how they interact with other bits of the >> system can be invaluable, particularly when you don't have the entire code >> base in front of you. >> > >> >> >> >> > >> >> >> For example, I just wrote a tool that explores the >> distribution of keys across multiple sstables, I needed some of the tools >> classes but not much more. Javadocs would have made that easy if I did not >> have the source code in front of me. >> > >> >> >> >> > >> >> >> I am -1 on removing the javadocs. >> >
Re: [DISCUSSION] Shall we remove ant javadoc task?
keep it we should fix things and add the > task to CI, if we don’t because no one wants the html pages - then better > to remove it this ant task. > > >> > On your comment about 100 errors - it seems they are more. There is > a cap of 100 but when you fix them, more errors appear. > > >> > Further discussion can be found at CASSANDRA-17687 > > >> > > > >> > On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov > wrote: > > >> >> > > >> >> Personally, I find javadocs quite useful, especially when htmls are > > >> >> indexed by search engines, which in turn increases the chances of > > >> >> finding the right answer faster (I have seen a lot of useful > javadocs > > >> >> in the source code). > > >> >> > > >> >> I have done a quick build of the javadocs: > > >> >> > > >> >> [javadoc] Building index for all the packages and classes... > > >> >> [javadoc] Building index for all classes... > > >> >> [javadoc] Building index for all classes... > > >> >> [javadoc] 100 errors > > >> >> [javadoc] 100 warnings > > >> >> > > >> >> 100 errors is no big deal and can be easily fixed. From my point of > > >> >> view, the problem is that the javadoc task is not given the > attention > > >> >> it deserves. The failonerror is currently 'false' and the task > itself > > >> >> is not a part of any build and/or release processes, correct me if > I'm > > >> >> wrong. > > >> >> > > >> >> So, > > >> >> 1. Fix warnings/errors; > > >> >> 2. Make the javadoc task part of the build (e.g. put it under > > >> >> 'artifacts'), or make it part of the release process that is > regularly > > >> >> checked on the CI; > > >> >> 3. Publish/deploy the javadoc htmls for release in the special > > >> >> directory of the cassandra website to give them a chance of being > > >> >> indexed; > > >> >> > > >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan < > [email protected]> wrote: > > >> >> > > > >> >> > I don’t think anyone wants to remove the javadocs. This thread > is about removing the broken ant task which generates html files from them. > > >> >> > > > >> >> > +1 from me on removing the ant task. If someone feels the task > is useful they can always implement one that does not crash and add it back. > > >> >> > > > >> >> > -Jeremiah > > >> >> > > > >> >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" < > [email protected]> wrote: > > >> >> >> > > >> >> >> I think that we can get more developers interested if there are > available javadocs. While many of the core classes are not going to be > touched by someone just starting, being able to understand what the > external touch points are and how they interact with other bits of the > system can be invaluable, particularly when you don't have the entire code > base in front of you. > > >> >> >> > > >> >> >> For example, I just wrote a tool that explores the distribution > of keys across multiple sstables, I needed some of the tools classes but > not much more. Javadocs would have made that easy if I did not have the > source code in front of me. > > >> >> >> > > >> >> >> I am -1 on removing the javadocs. > > >> >> >> > > >> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie < > [email protected]> wrote: > > >> >> >>> > > >> >> >>> If anything, the codebase could use a little more > package/class/method markup in some places > > >> >> >>> > > >> >> >>> I am impressed with how diplomatic and generous you're being > here Derek. :D > > >> >> >>> > > >> >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > > >> >> >>> > > >> >> >>> That is a good idea. I would like to have Javadocs valid when > going through them in IDE. To enforce it, we w
Re: [DISCUSSION] Shall we remove ant javadoc task?
gt; On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov wrote: > >> >> > >> >> Personally, I find javadocs quite useful, especially when htmls are > >> >> indexed by search engines, which in turn increases the chances of > >> >> finding the right answer faster (I have seen a lot of useful javadocs > >> >> in the source code). > >> >> > >> >> I have done a quick build of the javadocs: > >> >> > >> >> [javadoc] Building index for all the packages and classes... > >> >> [javadoc] Building index for all classes... > >> >> [javadoc] Building index for all classes... > >> >> [javadoc] 100 errors > >> >> [javadoc] 100 warnings > >> >> > >> >> 100 errors is no big deal and can be easily fixed. From my point of > >> >> view, the problem is that the javadoc task is not given the attention > >> >> it deserves. The failonerror is currently 'false' and the task itself > >> >> is not a part of any build and/or release processes, correct me if I'm > >> >> wrong. > >> >> > >> >> So, > >> >> 1. Fix warnings/errors; > >> >> 2. Make the javadoc task part of the build (e.g. put it under > >> >> 'artifacts'), or make it part of the release process that is regularly > >> >> checked on the CI; > >> >> 3. Publish/deploy the javadoc htmls for release in the special > >> >> directory of the cassandra website to give them a chance of being > >> >> indexed; > >> >> > >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan > >> >> wrote: > >> >> > > >> >> > I don’t think anyone wants to remove the javadocs. This thread is > >> >> > about removing the broken ant task which generates html files from > >> >> > them. > >> >> > > >> >> > +1 from me on removing the ant task. If someone feels the task is > >> >> > useful they can always implement one that does not crash and add it > >> >> > back. > >> >> > > >> >> > -Jeremiah > >> >> > > >> >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" > >> >> > wrote: > >> >> >> > >> >> >> I think that we can get more developers interested if there are > >> >> >> available javadocs. While many of the core classes are not going to > >> >> >> be touched by someone just starting, being able to understand what > >> >> >> the external touch points are and how they interact with other bits > >> >> >> of the system can be invaluable, particularly when you don't have > >> >> >> the entire code base in front of you. > >> >> >> > >> >> >> For example, I just wrote a tool that explores the distribution of > >> >> >> keys across multiple sstables, I needed some of the tools classes > >> >> >> but not much more. Javadocs would have made that easy if I did not > >> >> >> have the source code in front of me. > >> >> >> > >> >> >> I am -1 on removing the javadocs. > >> >> >> > >> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie > >> >> >> wrote: > >> >> >>> > >> >> >>> If anything, the codebase could use a little more > >> >> >>> package/class/method markup in some places > >> >> >>> > >> >> >>> I am impressed with how diplomatic and generous you're being here > >> >> >>> Derek. :D > >> >> >>> > >> >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > >> >> >>> > >> >> >>> That is a good idea. I would like to have Javadocs valid when going > >> >> >>> through them in IDE. To enforce it, we would have to fix it first. > >> >> >>> If we find a way how to validate Javadocs without actually > >> >> >>> rendering them, that would be cool. > >> >> >>> > >> >> >>> There is a lot of legacy and rewriting of some custom-crafted > >> >
Re: [DISCUSSION] Shall we remove ant javadoc task?
big deal and can be easily fixed. From my point of >> >> view, the problem is that the javadoc task is not given the attention >> >> it deserves. The failonerror is currently 'false' and the task itself >> >> is not a part of any build and/or release processes, correct me if I'm >> >> wrong. >> >> >> >> So, >> >> 1. Fix warnings/errors; >> >> 2. Make the javadoc task part of the build (e.g. put it under >> >> 'artifacts'), or make it part of the release process that is regularly >> >> checked on the CI; >> >> 3. Publish/deploy the javadoc htmls for release in the special >> >> directory of the cassandra website to give them a chance of being >> >> indexed; >> >> >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan >> >> wrote: >> >> > >> >> > I don’t think anyone wants to remove the javadocs. This thread is >> >> > about removing the broken ant task which generates html files from them. >> >> > >> >> > +1 from me on removing the ant task. If someone feels the task is >> >> > useful they can always implement one that does not crash and add it >> >> > back. >> >> > >> >> > -Jeremiah >> >> > >> >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" >> >> > wrote: >> >> >> >> >> >> I think that we can get more developers interested if there are >> >> >> available javadocs. While many of the core classes are not going to >> >> >> be touched by someone just starting, being able to understand what the >> >> >> external touch points are and how they interact with other bits of the >> >> >> system can be invaluable, particularly when you don't have the entire >> >> >> code base in front of you. >> >> >> >> >> >> For example, I just wrote a tool that explores the distribution of >> >> >> keys across multiple sstables, I needed some of the tools classes but >> >> >> not much more. Javadocs would have made that easy if I did not have >> >> >> the source code in front of me. >> >> >> >> >> >> I am -1 on removing the javadocs. >> >> >> >> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie >> >> >> wrote: >> >> >>> >> >> >>> If anything, the codebase could use a little more >> >> >>> package/class/method markup in some places >> >> >>> >> >> >>> I am impressed with how diplomatic and generous you're being here >> >> >>> Derek. :D >> >> >>> >> >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: >> >> >>> >> >> >>> That is a good idea. I would like to have Javadocs valid when going >> >> >>> through them in IDE. To enforce it, we would have to fix it first. If >> >> >>> we find a way how to validate Javadocs without actually rendering >> >> >>> them, that would be cool. >> >> >>> >> >> >>> There is a lot of legacy and rewriting of some custom-crafted >> >> >>> formatting of some comments might be quite a tedious task to do if it >> >> >>> is required to have them valid. I am in general for valid >> >> >>> documentation and even enforcing it but what to do with what is >> >> >>> already there ... >> >> >>> >> >> >>> >> >> >>> From: Jacek Lewandowski >> >> >>> Sent: Wednesday, August 2, 2023 23:38 >> >> >>> To: [email protected] >> >> >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? >> >> >>> >> >> >>> NetApp Security WARNING: This is an external email. Do not click >> >> >>> links or open attachments unless you recognize the sender and know >> >> >>> the content is safe. >> >> >>> >> >> >>> >> >> >>> >> >> >>> With or without outputting JavaDoc to HTML, there are some errors >> >> >>> which we shou
Re: [DISCUSSION] Shall we remove ant javadoc task?
> >> 3. Publish/deploy the javadoc htmls for release in the special > >> directory of the cassandra website to give them a chance of being > >> indexed; > >> > >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan > wrote: > >> > > >> > I don’t think anyone wants to remove the javadocs. This thread is > about removing the broken ant task which generates html files from them. > >> > > >> > +1 from me on removing the ant task. If someone feels the task is > useful they can always implement one that does not crash and add it back. > >> > > >> > -Jeremiah > >> > > >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" < > [email protected]> wrote: > >> >> > >> >> I think that we can get more developers interested if there are > available javadocs. While many of the core classes are not going to be > touched by someone just starting, being able to understand what the > external touch points are and how they interact with other bits of the > system can be invaluable, particularly when you don't have the entire code > base in front of you. > >> >> > >> >> For example, I just wrote a tool that explores the distribution of > keys across multiple sstables, I needed some of the tools classes but not > much more. Javadocs would have made that easy if I did not have the source > code in front of me. > >> >> > >> >> I am -1 on removing the javadocs. > >> >> > >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie > wrote: > >> >>> > >> >>> If anything, the codebase could use a little more > package/class/method markup in some places > >> >>> > >> >>> I am impressed with how diplomatic and generous you're being here > Derek. :D > >> >>> > >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > >> >>> > >> >>> That is a good idea. I would like to have Javadocs valid when going > through them in IDE. To enforce it, we would have to fix it first. If we > find a way how to validate Javadocs without actually rendering them, that > would be cool. > >> >>> > >> >>> There is a lot of legacy and rewriting of some custom-crafted > formatting of some comments might be quite a tedious task to do if it is > required to have them valid. I am in general for valid documentation and > even enforcing it but what to do with what is already there ... > >> >>> > >> >>> > >> >>> From: Jacek Lewandowski > >> >>> Sent: Wednesday, August 2, 2023 23:38 > >> >>> To: [email protected] > >> >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > >> >>> > >> >>> NetApp Security WARNING: This is an external email. Do not click > links or open attachments unless you recognize the sender and know the > content is safe. > >> >>> > >> >>> > >> >>> > >> >>> With or without outputting JavaDoc to HTML, there are some errors > which we should maybe fix. We want to keep the documentation, but there can > be syntax errors which may prevent IDE generating a proper preview. So, the > question is - should we validate the JavaDoc comments as a precommit task? > Can it be done without actually generating HTML output? > >> >>> > >> >>> Thanks, > >> >>> Jacek > >> >>> > >> >>> śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker < > [email protected]<mailto:[email protected]>> napisał: > >> >>> Oh, whoops, I guess I'm the only one that thinks Javadoc is just > the tool and/or it's output (not the markup itself) :P If anything, the > codebase could use a little more package/class/method markup in some > places, so I'm definitely only in favor of getting rid of the ant task. I > should amend my statement to be "...I suspect most people are not opening > their browsers and looking at Javadoc..." :) > >> >>> > >> >>> Cheers, > >> >>> > >> >>> Derek > >> >>> > >> >>> > >> >>> > >> >>> On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie <mailto:[email protected]>> wrote: > >> >>
Re: [DISCUSSION] Shall we remove ant javadoc task?
website to give them a chance of being >> >> indexed; >> >> >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan >> >> wrote: >> >> > >> >> > I don’t think anyone wants to remove the javadocs. This thread is >> >> > about removing the broken ant task which generates html files from them. >> >> > >> >> > +1 from me on removing the ant task. If someone feels the task is >> >> > useful they can always implement one that does not crash and add it >> >> > back. >> >> > >> >> > -Jeremiah >> >> > >> >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" >> >> > wrote: >> >> >> >> >> >> I think that we can get more developers interested if there are >> >> >> available javadocs. While many of the core classes are not going to >> >> >> be touched by someone just starting, being able to understand what the >> >> >> external touch points are and how they interact with other bits of the >> >> >> system can be invaluable, particularly when you don't have the entire >> >> >> code base in front of you. >> >> >> >> >> >> For example, I just wrote a tool that explores the distribution of >> >> >> keys across multiple sstables, I needed some of the tools classes but >> >> >> not much more. Javadocs would have made that easy if I did not have >> >> >> the source code in front of me. >> >> >> >> >> >> I am -1 on removing the javadocs. >> >> >> >> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie >> >> >> wrote: >> >> >>> >> >> >>> If anything, the codebase could use a little more >> >> >>> package/class/method markup in some places >> >> >>> >> >> >>> I am impressed with how diplomatic and generous you're being here >> >> >>> Derek. :D >> >> >>> >> >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: >> >> >>> >> >> >>> That is a good idea. I would like to have Javadocs valid when going >> >> >>> through them in IDE. To enforce it, we would have to fix it first. If >> >> >>> we find a way how to validate Javadocs without actually rendering >> >> >>> them, that would be cool. >> >> >>> >> >> >>> There is a lot of legacy and rewriting of some custom-crafted >> >> >>> formatting of some comments might be quite a tedious task to do if it >> >> >>> is required to have them valid. I am in general for valid >> >> >>> documentation and even enforcing it but what to do with what is >> >> >>> already there ... >> >> >>> >> >> >>> >> >> >>> From: Jacek Lewandowski >> >> >>> Sent: Wednesday, August 2, 2023 23:38 >> >> >>> To: [email protected] >> >> >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? >> >> >>> >> >> >>> NetApp Security WARNING: This is an external email. Do not click >> >> >>> links or open attachments unless you recognize the sender and know >> >> >>> the content is safe. >> >> >>> >> >> >>> >> >> >>> >> >> >>> With or without outputting JavaDoc to HTML, there are some errors >> >> >>> which we should maybe fix. We want to keep the documentation, but >> >> >>> there can be syntax errors which may prevent IDE generating a proper >> >> >>> preview. So, the question is - should we validate the JavaDoc >> >> >>> comments as a precommit task? Can it be done without actually >> >> >>> generating HTML output? >> >> >>> >> >> >>> Thanks, >> >> >>> Jacek >> >> >>> >> >> >>> śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker >> >> >>> mailto:[email protected]>> napisał: >> >> >>> Oh, whoops, I guess I'm the only one that think
Re: [DISCUSSION] Shall we remove ant javadoc task?
>> I am -1 on removing the javadocs. > >> >> > >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie > wrote: > >> >>> > >> >>> If anything, the codebase could use a little more > package/class/method markup in some places > >> >>> > >> >>> I am impressed with how diplomatic and generous you're being here > Derek. :D > >> >>> > >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > >> >>> > >> >>> That is a good idea. I would like to have Javadocs valid when going > through them in IDE. To enforce it, we would have to fix it first. If we > find a way how to validate Javadocs without actually rendering them, that > would be cool. > >> >>> > >> >>> There is a lot of legacy and rewriting of some custom-crafted > formatting of some comments might be quite a tedious task to do if it is > required to have them valid. I am in general for valid documentation and > even enforcing it but what to do with what is already there ... > >> >>> > >> >>> > >> >>> From: Jacek Lewandowski > >> >>> Sent: Wednesday, August 2, 2023 23:38 > >> >>> To: [email protected] > >> >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > >> >>> > >> >>> NetApp Security WARNING: This is an external email. Do not click > links or open attachments unless you recognize the sender and know the > content is safe. > >> >>> > >> >>> > >> >>> > >> >>> With or without outputting JavaDoc to HTML, there are some errors > which we should maybe fix. We want to keep the documentation, but there can > be syntax errors which may prevent IDE generating a proper preview. So, the > question is - should we validate the JavaDoc comments as a precommit task? > Can it be done without actually generating HTML output? > >> >>> > >> >>> Thanks, > >> >>> Jacek > >> >>> > >> >>> śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker < > [email protected]<mailto:[email protected]>> napisał: > >> >>> Oh, whoops, I guess I'm the only one that thinks Javadoc is just > the tool and/or it's output (not the markup itself) :P If anything, the > codebase could use a little more package/class/method markup in some > places, so I'm definitely only in favor of getting rid of the ant task. I > should amend my statement to be "...I suspect most people are not opening > their browsers and looking at Javadoc..." :) > >> >>> > >> >>> Cheers, > >> >>> > >> >>> Derek > >> >>> > >> >>> > >> >>> > >> >>> On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie <mailto:[email protected]>> wrote: > >> >>> most people are not looking at Javadoc when working on the codebase. > >> >>> I definitely use it extensively inside the IDE. But never as a > compiled set of external docs. > >> >>> > >> >>> Which is to say, I'm +1 on removing the target and I'd ask everyone > to keep javadoccing your classes and methods where things are non-obvious > or there's a logical coupling with something else in the system. :) > >> >>> > >> >>> On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > >> >>> +1. If a need comes up for Javadoc we can fix it at that point, but > I suspect most people are not looking at Javadoc when working on the > codebase. > >> >>> > >> >>> Cheers, > >> >>> > >> >>> Derek > >> >>> > >> >>> On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams <mailto:[email protected]>> wrote: > >> >>> I don't think even if it works anyone is going to use the output, so > >> >>> I'm good with removal. > >> >>> > >> >>> Kind Regards, > >> >>> Brandon > >> >>> > >> >>> On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > >> >>> mailto:[email protected]>> wrote: > >> >>> > > >> >>> > Hi everyone, > >> >>> > We were looking into a user report around our ant javadoc task > recently. > >> >>> > That made us realize it is not run in CI; it finishes > successfully even if there are hundreds of errors, some potentially > breaking doc pages. > >> >>> > > >> >>> > There was a ticket discussion where a few community members > mentioned that this task was probably unnecessary. Can we remove it, or > shall we fix it? > >> >>> > > >> >>> > Best regards, > >> >>> > Ekaterina > >> >>> > >> >>> > >> >>> -- > >> >>> +---+ > >> >>> | Derek Chen-Becker | > >> >>> | GPG Key available at https://keybase.io/dchenbecker< > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fkeybase.io%2Fdchenbecker&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373361824%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=n%2BrDfikzzoQG%2Fg%2BRvNqEEE6vHP8ZmY1skeosesLK9v0%3D&reserved=0> > and | > >> >>> | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org< > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpgp.mit.edu%2Fpks%2Flookup%3Fsearch%3Dderek%2540chen-becker.org&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373518054%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Tnu5cIoIFZGqhaqOjCjW8yK%2BDTT2%2B0ifvFNs1pJO93s%3D&reserved=0> > | > >> >>> | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | > >> >>> +---+ > >> >>> > >> >>> > >> >>> > >> >>> >
Re: [DISCUSSION] Shall we remove ant javadoc task?
Yes, I agree. The javadoc task should be part of our CI if we decide to keep it, to keep it buildable at all times. BTW, I have managed to fix all the javadoc errors. I have tested the task for both jdk11 and jdk17. Changes are here: https://github.com/apache/cassandra/compare/trunk...Mmuzaf:cassandra:javadoc_build On Thu, 3 Aug 2023 at 21:20, Ekaterina Dimitrova wrote: > > Thank you Maxim, > > “ > > From my point of > view, the problem is that the javadoc task is not given the attention > it deserves. The failonerror is currently 'false' and the task itself > is not a part of any build and/or release processes, correct me if I'm > wrong. > > So, > 1. Fix warnings/errors; > 2. Make the javadoc task part of the build (e.g. put it under > 'artifacts'), or make it part of the release process that is regularly > checked on the CI; > 3. Publish/deploy the javadoc htmls for release in the special > directory of the cassandra website to give them a chance of being > indexed;“ > > This is aligned with what I saw and the two options mentioned at the > beginning - if we decide to keep it we should fix things and add the task to > CI, if we don’t because no one wants the html pages - then better to remove > it this ant task. > On your comment about 100 errors - it seems they are more. There is a cap of > 100 but when you fix them, more errors appear. > Further discussion can be found at CASSANDRA-17687 > > On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov wrote: >> >> Personally, I find javadocs quite useful, especially when htmls are >> indexed by search engines, which in turn increases the chances of >> finding the right answer faster (I have seen a lot of useful javadocs >> in the source code). >> >> I have done a quick build of the javadocs: >> >> [javadoc] Building index for all the packages and classes... >> [javadoc] Building index for all classes... >> [javadoc] Building index for all classes... >> [javadoc] 100 errors >> [javadoc] 100 warnings >> >> 100 errors is no big deal and can be easily fixed. From my point of >> view, the problem is that the javadoc task is not given the attention >> it deserves. The failonerror is currently 'false' and the task itself >> is not a part of any build and/or release processes, correct me if I'm >> wrong. >> >> So, >> 1. Fix warnings/errors; >> 2. Make the javadoc task part of the build (e.g. put it under >> 'artifacts'), or make it part of the release process that is regularly >> checked on the CI; >> 3. Publish/deploy the javadoc htmls for release in the special >> directory of the cassandra website to give them a chance of being >> indexed; >> >> On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan >> wrote: >> > >> > I don’t think anyone wants to remove the javadocs. This thread is about >> > removing the broken ant task which generates html files from them. >> > >> > +1 from me on removing the ant task. If someone feels the task is useful >> > they can always implement one that does not crash and add it back. >> > >> > -Jeremiah >> > >> > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" >> > wrote: >> >> >> >> I think that we can get more developers interested if there are available >> >> javadocs. While many of the core classes are not going to be touched by >> >> someone just starting, being able to understand what the external touch >> >> points are and how they interact with other bits of the system can be >> >> invaluable, particularly when you don't have the entire code base in >> >> front of you. >> >> >> >> For example, I just wrote a tool that explores the distribution of keys >> >> across multiple sstables, I needed some of the tools classes but not much >> >> more. Javadocs would have made that easy if I did not have the source >> >> code in front of me. >> >> >> >> I am -1 on removing the javadocs. >> >> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie wrote: >> >>> >> >>> If anything, the codebase could use a little more package/class/method >> >>> markup in some places >> >>> >> >>> I am impressed with how diplomatic and generous you're being here Derek. >> >>> :D >> >>> >> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: >> >>> >> &g
Re: [DISCUSSION] Shall we remove ant javadoc task?
Thank you Maxim, “ >From my point of view, the problem is that the javadoc task is not given the attention it deserves. The failonerror is currently 'false' and the task itself is not a part of any build and/or release processes, correct me if I'm wrong. So, 1. Fix warnings/errors; 2. Make the javadoc task part of the build (e.g. put it under 'artifacts'), or make it part of the release process that is regularly checked on the CI; 3. Publish/deploy the javadoc htmls for release in the special directory of the cassandra website to give them a chance of being indexed;“ This is aligned with what I saw and the two options mentioned at the beginning - if we decide to keep it we should fix things and add the task to CI, if we don’t because no one wants the html pages - then better to remove it this ant task. On your comment about 100 errors - it seems they are more. There is a cap of 100 but when you fix them, more errors appear. Further discussion can be found at CASSANDRA-17687 On Thu, 3 Aug 2023 at 14:21, Maxim Muzafarov wrote: > Personally, I find javadocs quite useful, especially when htmls are > indexed by search engines, which in turn increases the chances of > finding the right answer faster (I have seen a lot of useful javadocs > in the source code). > > I have done a quick build of the javadocs: > > [javadoc] Building index for all the packages and classes... > [javadoc] Building index for all classes... > [javadoc] Building index for all classes... > [javadoc] 100 errors > [javadoc] 100 warnings > > 100 errors is no big deal and can be easily fixed. From my point of > view, the problem is that the javadoc task is not given the attention > it deserves. The failonerror is currently 'false' and the task itself > is not a part of any build and/or release processes, correct me if I'm > wrong. > > So, > 1. Fix warnings/errors; > 2. Make the javadoc task part of the build (e.g. put it under > 'artifacts'), or make it part of the release process that is regularly > checked on the CI; > 3. Publish/deploy the javadoc htmls for release in the special > directory of the cassandra website to give them a chance of being > indexed; > > On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan > wrote: > > > > I don’t think anyone wants to remove the javadocs. This thread is about > removing the broken ant task which generates html files from them. > > > > +1 from me on removing the ant task. If someone feels the task is > useful they can always implement one that does not crash and add it back. > > > > -Jeremiah > > > > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" < > [email protected]> wrote: > >> > >> I think that we can get more developers interested if there are > available javadocs. While many of the core classes are not going to be > touched by someone just starting, being able to understand what the > external touch points are and how they interact with other bits of the > system can be invaluable, particularly when you don't have the entire code > base in front of you. > >> > >> For example, I just wrote a tool that explores the distribution of keys > across multiple sstables, I needed some of the tools classes but not much > more. Javadocs would have made that easy if I did not have the source code > in front of me. > >> > >> I am -1 on removing the javadocs. > >> > >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie > wrote: > >>> > >>> If anything, the codebase could use a little more package/class/method > markup in some places > >>> > >>> I am impressed with how diplomatic and generous you're being here > Derek. :D > >>> > >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > >>> > >>> That is a good idea. I would like to have Javadocs valid when going > through them in IDE. To enforce it, we would have to fix it first. If we > find a way how to validate Javadocs without actually rendering them, that > would be cool. > >>> > >>> There is a lot of legacy and rewriting of some custom-crafted > formatting of some comments might be quite a tedious task to do if it is > required to have them valid. I am in general for valid documentation and > even enforcing it but what to do with what is already there ... > >>> > >>> > >>> From: Jacek Lewandowski > >>> Sent: Wednesday, August 2, 2023 23:38 > >>> To: [email protected] > >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > &g
Re: [DISCUSSION] Shall we remove ant javadoc task?
Personally, I find javadocs quite useful, especially when htmls are indexed by search engines, which in turn increases the chances of finding the right answer faster (I have seen a lot of useful javadocs in the source code). I have done a quick build of the javadocs: [javadoc] Building index for all the packages and classes... [javadoc] Building index for all classes... [javadoc] Building index for all classes... [javadoc] 100 errors [javadoc] 100 warnings 100 errors is no big deal and can be easily fixed. From my point of view, the problem is that the javadoc task is not given the attention it deserves. The failonerror is currently 'false' and the task itself is not a part of any build and/or release processes, correct me if I'm wrong. So, 1. Fix warnings/errors; 2. Make the javadoc task part of the build (e.g. put it under 'artifacts'), or make it part of the release process that is regularly checked on the CI; 3. Publish/deploy the javadoc htmls for release in the special directory of the cassandra website to give them a chance of being indexed; On Thu, 3 Aug 2023 at 17:11, Jeremiah Jordan wrote: > > I don’t think anyone wants to remove the javadocs. This thread is about > removing the broken ant task which generates html files from them. > > +1 from me on removing the ant task. If someone feels the task is useful > they can always implement one that does not crash and add it back. > > -Jeremiah > > On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" > wrote: >> >> I think that we can get more developers interested if there are available >> javadocs. While many of the core classes are not going to be touched by >> someone just starting, being able to understand what the external touch >> points are and how they interact with other bits of the system can be >> invaluable, particularly when you don't have the entire code base in front >> of you. >> >> For example, I just wrote a tool that explores the distribution of keys >> across multiple sstables, I needed some of the tools classes but not much >> more. Javadocs would have made that easy if I did not have the source code >> in front of me. >> >> I am -1 on removing the javadocs. >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie wrote: >>> >>> If anything, the codebase could use a little more package/class/method >>> markup in some places >>> >>> I am impressed with how diplomatic and generous you're being here Derek. :D >>> >>> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: >>> >>> That is a good idea. I would like to have Javadocs valid when going through >>> them in IDE. To enforce it, we would have to fix it first. If we find a way >>> how to validate Javadocs without actually rendering them, that would be >>> cool. >>> >>> There is a lot of legacy and rewriting of some custom-crafted formatting of >>> some comments might be quite a tedious task to do if it is required to have >>> them valid. I am in general for valid documentation and even enforcing it >>> but what to do with what is already there ... >>> >>> >>> From: Jacek Lewandowski >>> Sent: Wednesday, August 2, 2023 23:38 >>> To: [email protected] >>> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? >>> >>> NetApp Security WARNING: This is an external email. Do not click links or >>> open attachments unless you recognize the sender and know the content is >>> safe. >>> >>> >>> >>> With or without outputting JavaDoc to HTML, there are some errors which we >>> should maybe fix. We want to keep the documentation, but there can be >>> syntax errors which may prevent IDE generating a proper preview. So, the >>> question is - should we validate the JavaDoc comments as a precommit task? >>> Can it be done without actually generating HTML output? >>> >>> Thanks, >>> Jacek >>> >>> śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker >>> mailto:[email protected]>> napisał: >>> Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool >>> and/or it's output (not the markup itself) :P If anything, the codebase >>> could use a little more package/class/method markup in some places, so I'm >>> definitely only in favor of getting rid of the ant task. I should amend my >>> statement to be "...I suspect most people are not opening their browsers >>>
Re: [DISCUSSION] Shall we remove ant javadoc task?
I don’t think anyone wants to remove the javadocs. This thread is about removing the broken ant task which generates html files from them. +1 from me on removing the ant task. If someone feels the task is useful they can always implement one that does not crash and add it back. -Jeremiah On Aug 3, 2023 at 9:59:55 AM, "Claude Warren, Jr via dev" < [email protected]> wrote: > I think that we can get more developers interested if there are available > javadocs. While many of the core classes are not going to be touched by > someone just starting, being able to understand what the external touch > points are and how they interact with other bits of the system can be > invaluable, particularly when you don't have the entire code base in front > of you. > > For example, I just wrote a tool that explores the distribution of keys > across multiple sstables, I needed some of the tools classes but not much > more. Javadocs would have made that easy if I did not have the source code > in front of me. > > I am -1 on removing the javadocs. > > On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie wrote: > >> If anything, the codebase could use a little more package/class/method >> markup in some places >> >> I am impressed with how diplomatic and generous you're being here Derek. >> :D >> >> On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: >> >> That is a good idea. I would like to have Javadocs valid when going >> through them in IDE. To enforce it, we would have to fix it first. If we >> find a way how to validate Javadocs without actually rendering them, that >> would be cool. >> >> There is a lot of legacy and rewriting of some custom-crafted formatting >> of some comments might be quite a tedious task to do if it is required to >> have them valid. I am in general for valid documentation and even enforcing >> it but what to do with what is already there ... >> >> ________ >> From: Jacek Lewandowski >> Sent: Wednesday, August 2, 2023 23:38 >> To: [email protected] >> Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? >> >> NetApp Security WARNING: This is an external email. Do not click links or >> open attachments unless you recognize the sender and know the content is >> safe. >> >> >> >> With or without outputting JavaDoc to HTML, there are some errors which >> we should maybe fix. We want to keep the documentation, but there can be >> syntax errors which may prevent IDE generating a proper preview. So, the >> question is - should we validate the JavaDoc comments as a precommit task? >> Can it be done without actually generating HTML output? >> >> Thanks, >> Jacek >> >> śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker < >> [email protected]<mailto:[email protected]>> napisał: >> Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool >> and/or it's output (not the markup itself) :P If anything, the codebase >> could use a little more package/class/method markup in some places, so I'm >> definitely only in favor of getting rid of the ant task. I should amend my >> statement to be "...I suspect most people are not opening their browsers >> and looking at Javadoc..." :) >> >> Cheers, >> >> Derek >> >> >> >> On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie > [email protected]>> wrote: >> most people are not looking at Javadoc when working on the codebase. >> I definitely use it extensively inside the IDE. But never as a compiled >> set of external docs. >> >> Which is to say, I'm +1 on removing the target and I'd ask everyone to >> keep javadoccing your classes and methods where things are non-obvious or >> there's a logical coupling with something else in the system. :) >> >> On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: >> +1. If a need comes up for Javadoc we can fix it at that point, but I >> suspect most people are not looking at Javadoc when working on the codebase. >> >> Cheers, >> >> Derek >> >> On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams > <mailto:[email protected]>> wrote: >> I don't think even if it works anyone is going to use the output, so >> I'm good with removal. >> >> Kind Regards, >> Brandon >> >> On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova >> mailto:[email protected]>> wrote: >> > >> > Hi everyone, >> > We were lookin
Re: [DISCUSSION] Shall we remove ant javadoc task?
I think that we can get more developers interested if there are available javadocs. While many of the core classes are not going to be touched by someone just starting, being able to understand what the external touch points are and how they interact with other bits of the system can be invaluable, particularly when you don't have the entire code base in front of you. For example, I just wrote a tool that explores the distribution of keys across multiple sstables, I needed some of the tools classes but not much more. Javadocs would have made that easy if I did not have the source code in front of me. I am -1 on removing the javadocs. On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie wrote: > If anything, the codebase could use a little more package/class/method > markup in some places > > I am impressed with how diplomatic and generous you're being here Derek. :D > > On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > > That is a good idea. I would like to have Javadocs valid when going > through them in IDE. To enforce it, we would have to fix it first. If we > find a way how to validate Javadocs without actually rendering them, that > would be cool. > > There is a lot of legacy and rewriting of some custom-crafted formatting > of some comments might be quite a tedious task to do if it is required to > have them valid. I am in general for valid documentation and even enforcing > it but what to do with what is already there ... > > > From: Jacek Lewandowski > Sent: Wednesday, August 2, 2023 23:38 > To: [email protected] > Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > > NetApp Security WARNING: This is an external email. Do not click links or > open attachments unless you recognize the sender and know the content is > safe. > > > > With or without outputting JavaDoc to HTML, there are some errors which we > should maybe fix. We want to keep the documentation, but there can be > syntax errors which may prevent IDE generating a proper preview. So, the > question is - should we validate the JavaDoc comments as a precommit task? > Can it be done without actually generating HTML output? > > Thanks, > Jacek > > śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker <mailto:[email protected]>> napisał: > Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool > and/or it's output (not the markup itself) :P If anything, the codebase > could use a little more package/class/method markup in some places, so I'm > definitely only in favor of getting rid of the ant task. I should amend my > statement to be "...I suspect most people are not opening their browsers > and looking at Javadoc..." :) > > Cheers, > > Derek > > > > On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie [email protected]>> wrote: > most people are not looking at Javadoc when working on the codebase. > I definitely use it extensively inside the IDE. But never as a compiled > set of external docs. > > Which is to say, I'm +1 on removing the target and I'd ask everyone to > keep javadoccing your classes and methods where things are non-obvious or > there's a logical coupling with something else in the system. :) > > On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > +1. If a need comes up for Javadoc we can fix it at that point, but I > suspect most people are not looking at Javadoc when working on the codebase. > > Cheers, > > Derek > > On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams [email protected]>> wrote: > I don't think even if it works anyone is going to use the output, so > I'm good with removal. > > Kind Regards, > Brandon > > On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > mailto:[email protected]>> wrote: > > > > Hi everyone, > > We were looking into a user report around our ant javadoc task recently. > > That made us realize it is not run in CI; it finishes successfully even > if there are hundreds of errors, some potentially breaking doc pages. > > > > There was a ticket discussion where a few community members mentioned > that this task was probably unnecessary. Can we remove it, or shall we fix > it? > > > > Best regards, > > Ekaterina > > > -- > +---+ > | Derek Chen-Becker | > | GPG Key available at https://keybase.io/dchenbecker< > https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fkeybase.io%2Fdchenbecker&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b
Re: [DISCUSSION] Shall we remove ant javadoc task?
> If anything, the codebase could use a little more package/class/method markup > in some places I am impressed with how diplomatic and generous you're being here Derek. :D On Wed, Aug 2, 2023, at 5:46 PM, Miklosovic, Stefan wrote: > That is a good idea. I would like to have Javadocs valid when going through > them in IDE. To enforce it, we would have to fix it first. If we find a way > how to validate Javadocs without actually rendering them, that would be cool. > > There is a lot of legacy and rewriting of some custom-crafted formatting of > some comments might be quite a tedious task to do if it is required to have > them valid. I am in general for valid documentation and even enforcing it but > what to do with what is already there ... > > > From: Jacek Lewandowski > Sent: Wednesday, August 2, 2023 23:38 > To: [email protected] > Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? > > NetApp Security WARNING: This is an external email. Do not click links or > open attachments unless you recognize the sender and know the content is safe. > > > > With or without outputting JavaDoc to HTML, there are some errors which we > should maybe fix. We want to keep the documentation, but there can be syntax > errors which may prevent IDE generating a proper preview. So, the question is > - should we validate the JavaDoc comments as a precommit task? Can it be done > without actually generating HTML output? > > Thanks, > Jacek > > śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker > mailto:[email protected]>> napisał: > Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool > and/or it's output (not the markup itself) :P If anything, the codebase could > use a little more package/class/method markup in some places, so I'm > definitely only in favor of getting rid of the ant task. I should amend my > statement to be "...I suspect most people are not opening their browsers and > looking at Javadoc..." :) > > Cheers, > > Derek > > > > On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie > mailto:[email protected]>> wrote: > most people are not looking at Javadoc when working on the codebase. > I definitely use it extensively inside the IDE. But never as a compiled set > of external docs. > > Which is to say, I'm +1 on removing the target and I'd ask everyone to keep > javadoccing your classes and methods where things are non-obvious or there's > a logical coupling with something else in the system. :) > > On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > +1. If a need comes up for Javadoc we can fix it at that point, but I suspect > most people are not looking at Javadoc when working on the codebase. > > Cheers, > > Derek > > On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams > mailto:[email protected]>> wrote: > I don't think even if it works anyone is going to use the output, so > I'm good with removal. > > Kind Regards, > Brandon > > On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > mailto:[email protected]>> wrote: > > > > Hi everyone, > > We were looking into a user report around our ant javadoc task recently. > > That made us realize it is not run in CI; it finishes successfully even if > > there are hundreds of errors, some potentially breaking doc pages. > > > > There was a ticket discussion where a few community members mentioned that > > this task was probably unnecessary. Can we remove it, or shall we fix it? > > > > Best regards, > > Ekaterina > > > -- > +---+ > | Derek Chen-Becker | > | GPG Key available at > https://keybase.io/dchenbecker<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fkeybase.io%2Fdchenbecker&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373361824%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=n%2BrDfikzzoQG%2Fg%2BRvNqEEE6vHP8ZmY1skeosesLK9v0%3D&reserved=0> > and | > | > https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpgp.mit.edu%2Fpks%2Flookup%3Fsearch%3Dderek%2540chen-becker.org&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373518054%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Tnu5cIoIFZGqhaqOjCjW8yK%2BDTT2%2B0ifvFNs1pJO93s%3D&reserved=0> > | > | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | > +---+ > > >
Re: [DISCUSSION] Shall we remove ant javadoc task?
That is a good idea. I would like to have Javadocs valid when going through them in IDE. To enforce it, we would have to fix it first. If we find a way how to validate Javadocs without actually rendering them, that would be cool. There is a lot of legacy and rewriting of some custom-crafted formatting of some comments might be quite a tedious task to do if it is required to have them valid. I am in general for valid documentation and even enforcing it but what to do with what is already there ... From: Jacek Lewandowski Sent: Wednesday, August 2, 2023 23:38 To: [email protected] Subject: Re: [DISCUSSION] Shall we remove ant javadoc task? NetApp Security WARNING: This is an external email. Do not click links or open attachments unless you recognize the sender and know the content is safe. With or without outputting JavaDoc to HTML, there are some errors which we should maybe fix. We want to keep the documentation, but there can be syntax errors which may prevent IDE generating a proper preview. So, the question is - should we validate the JavaDoc comments as a precommit task? Can it be done without actually generating HTML output? Thanks, Jacek śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker mailto:[email protected]>> napisał: Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool and/or it's output (not the markup itself) :P If anything, the codebase could use a little more package/class/method markup in some places, so I'm definitely only in favor of getting rid of the ant task. I should amend my statement to be "...I suspect most people are not opening their browsers and looking at Javadoc..." :) Cheers, Derek On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie mailto:[email protected]>> wrote: most people are not looking at Javadoc when working on the codebase. I definitely use it extensively inside the IDE. But never as a compiled set of external docs. Which is to say, I'm +1 on removing the target and I'd ask everyone to keep javadoccing your classes and methods where things are non-obvious or there's a logical coupling with something else in the system. :) On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: +1. If a need comes up for Javadoc we can fix it at that point, but I suspect most people are not looking at Javadoc when working on the codebase. Cheers, Derek On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams mailto:[email protected]>> wrote: I don't think even if it works anyone is going to use the output, so I'm good with removal. Kind Regards, Brandon On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova mailto:[email protected]>> wrote: > > Hi everyone, > We were looking into a user report around our ant javadoc task recently. > That made us realize it is not run in CI; it finishes successfully even if > there are hundreds of errors, some potentially breaking doc pages. > > There was a ticket discussion where a few community members mentioned that > this task was probably unnecessary. Can we remove it, or shall we fix it? > > Best regards, > Ekaterina -- +---+ | Derek Chen-Becker | | GPG Key available at https://keybase.io/dchenbecker<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fkeybase.io%2Fdchenbecker&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373361824%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=n%2BrDfikzzoQG%2Fg%2BRvNqEEE6vHP8ZmY1skeosesLK9v0%3D&reserved=0> and | | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fpgp.mit.edu%2Fpks%2Flookup%3Fsearch%3Dderek%2540chen-becker.org&data=05%7C01%7CStefan.Miklosovic%40netapp.com%7C7ca04f0f58764996ab1e08db93a0de2a%7C4b0911a0929b4715944bc03745165b3a%7C0%7C0%7C638266091373518054%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=Tnu5cIoIFZGqhaqOjCjW8yK%2BDTT2%2B0ifvFNs1pJO93s%3D&reserved=0> | | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | +---+
Re: [DISCUSSION] Shall we remove ant javadoc task?
With or without outputting JavaDoc to HTML, there are some errors which we should maybe fix. We want to keep the documentation, but there can be syntax errors which may prevent IDE generating a proper preview. So, the question is - should we validate the JavaDoc comments as a precommit task? Can it be done without actually generating HTML output? Thanks, Jacek śr., 2 sie 2023, 22:24 użytkownik Derek Chen-Becker napisał: > Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool > and/or it's output (not the markup itself) :P If anything, the codebase > could use a little more package/class/method markup in some places, so I'm > definitely only in favor of getting rid of the ant task. I should amend my > statement to be "...I suspect most people are not *opening their browsers > and *looking at Javadoc..." :) > > Cheers, > > Derek > > > > On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie wrote: > >> most people are not looking at Javadoc when working on the codebase. >> >> I definitely use it extensively *inside the IDE*. But never as a >> compiled set of external docs. >> >> Which is to say, I'm +1 on removing the target and I'd ask everyone to >> keep javadoccing your classes and methods where things are non-obvious or >> there's a logical coupling with something else in the system. :) >> >> On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: >> >> +1. If a need comes up for Javadoc we can fix it at that point, but I >> suspect most people are not looking at Javadoc when working on the codebase. >> >> Cheers, >> >> Derek >> >> On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams >> wrote: >> >> I don't think even if it works anyone is going to use the output, so >> I'm good with removal. >> >> Kind Regards, >> Brandon >> >> On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova >> wrote: >> > >> > Hi everyone, >> > We were looking into a user report around our ant javadoc task recently. >> > That made us realize it is not run in CI; it finishes successfully even >> if there are hundreds of errors, some potentially breaking doc pages. >> > >> > There was a ticket discussion where a few community members mentioned >> that this task was probably unnecessary. Can we remove it, or shall we fix >> it? >> > >> > Best regards, >> > Ekaterina >> >> >> >> -- >> +---+ >> | Derek Chen-Becker | >> | GPG Key available at https://keybase.io/dchenbecker and | >> | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | >> | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | >> +---+ >> >> >>
Re: [DISCUSSION] Shall we remove ant javadoc task?
Oh, whoops, I guess I'm the only one that thinks Javadoc is just the tool and/or it's output (not the markup itself) :P If anything, the codebase could use a little more package/class/method markup in some places, so I'm definitely only in favor of getting rid of the ant task. I should amend my statement to be "...I suspect most people are not *opening their browsers and *looking at Javadoc..." :) Cheers, Derek On Wed, Aug 2, 2023, 1:30 PM Josh McKenzie wrote: > most people are not looking at Javadoc when working on the codebase. > > I definitely use it extensively *inside the IDE*. But never as a compiled > set of external docs. > > Which is to say, I'm +1 on removing the target and I'd ask everyone to > keep javadoccing your classes and methods where things are non-obvious or > there's a logical coupling with something else in the system. :) > > On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > > +1. If a need comes up for Javadoc we can fix it at that point, but I > suspect most people are not looking at Javadoc when working on the codebase. > > Cheers, > > Derek > > On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams wrote: > > I don't think even if it works anyone is going to use the output, so > I'm good with removal. > > Kind Regards, > Brandon > > On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > wrote: > > > > Hi everyone, > > We were looking into a user report around our ant javadoc task recently. > > That made us realize it is not run in CI; it finishes successfully even > if there are hundreds of errors, some potentially breaking doc pages. > > > > There was a ticket discussion where a few community members mentioned > that this task was probably unnecessary. Can we remove it, or shall we fix > it? > > > > Best regards, > > Ekaterina > > > > -- > +---+ > | Derek Chen-Becker | > | GPG Key available at https://keybase.io/dchenbecker and | > | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | > | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | > +---+ > > >
Re: [DISCUSSION] Shall we remove ant javadoc task?
I second what Josh said and confirm we were talking only about the task, no one is going to remove javadoc from the source code and I totally encourage people to continue documenting the code On Wed, 2 Aug 2023 at 15:30, Josh McKenzie wrote: > most people are not looking at Javadoc when working on the codebase. > > I definitely use it extensively *inside the IDE*. But never as a compiled > set of external docs. > > Which is to say, I'm +1 on removing the target and I'd ask everyone to > keep javadoccing your classes and methods where things are non-obvious or > there's a logical coupling with something else in the system. :) > > On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > > +1. If a need comes up for Javadoc we can fix it at that point, but I > suspect most people are not looking at Javadoc when working on the codebase. > > Cheers, > > Derek > > On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams wrote: > > I don't think even if it works anyone is going to use the output, so > I'm good with removal. > > Kind Regards, > Brandon > > On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > wrote: > > > > Hi everyone, > > We were looking into a user report around our ant javadoc task recently. > > That made us realize it is not run in CI; it finishes successfully even > if there are hundreds of errors, some potentially breaking doc pages. > > > > There was a ticket discussion where a few community members mentioned > that this task was probably unnecessary. Can we remove it, or shall we fix > it? > > > > Best regards, > > Ekaterina > > > > -- > +---+ > | Derek Chen-Becker | > | GPG Key available at https://keybase.io/dchenbecker and | > | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | > | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | > +---+ > > >
Re: [DISCUSSION] Shall we remove ant javadoc task?
> most people are not looking at Javadoc when working on the codebase. I definitely use it extensively **inside the IDE**. But never as a compiled set of external docs. Which is to say, I'm +1 on removing the target and I'd ask everyone to keep javadoccing your classes and methods where things are non-obvious or there's a logical coupling with something else in the system. :) On Wed, Aug 2, 2023, at 2:08 PM, Derek Chen-Becker wrote: > +1. If a need comes up for Javadoc we can fix it at that point, but I suspect > most people are not looking at Javadoc when working on the codebase. > > Cheers, > > Derek > > On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams wrote: >> I don't think even if it works anyone is going to use the output, so >> I'm good with removal. >> >> Kind Regards, >> Brandon >> >> On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova >> wrote: >> > >> > Hi everyone, >> > We were looking into a user report around our ant javadoc task recently. >> > That made us realize it is not run in CI; it finishes successfully even if >> > there are hundreds of errors, some potentially breaking doc pages. >> > >> > There was a ticket discussion where a few community members mentioned that >> > this task was probably unnecessary. Can we remove it, or shall we fix it? >> > >> > Best regards, >> > Ekaterina > > > -- > +---+ > | Derek Chen-Becker | > | GPG Key available at https://keybase.io/dchenbecker and | > | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | > | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | > +---+ >
Re: [DISCUSSION] Shall we remove ant javadoc task?
+1. If a need comes up for Javadoc we can fix it at that point, but I suspect most people are not looking at Javadoc when working on the codebase. Cheers, Derek On Wed, Aug 2, 2023 at 11:11 AM Brandon Williams wrote: > I don't think even if it works anyone is going to use the output, so > I'm good with removal. > > Kind Regards, > Brandon > > On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova > wrote: > > > > Hi everyone, > > We were looking into a user report around our ant javadoc task recently. > > That made us realize it is not run in CI; it finishes successfully even > if there are hundreds of errors, some potentially breaking doc pages. > > > > There was a ticket discussion where a few community members mentioned > that this task was probably unnecessary. Can we remove it, or shall we fix > it? > > > > Best regards, > > Ekaterina > -- +---+ | Derek Chen-Becker | | GPG Key available at https://keybase.io/dchenbecker and | | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | +---+
Re: [DISCUSSION] Shall we remove ant javadoc task?
I don't think even if it works anyone is going to use the output, so I'm good with removal. Kind Regards, Brandon On Wed, Aug 2, 2023 at 11:50 AM Ekaterina Dimitrova wrote: > > Hi everyone, > We were looking into a user report around our ant javadoc task recently. > That made us realize it is not run in CI; it finishes successfully even if > there are hundreds of errors, some potentially breaking doc pages. > > There was a ticket discussion where a few community members mentioned that > this task was probably unnecessary. Can we remove it, or shall we fix it? > > Best regards, > Ekaterina
