+1 to `ant check` (and to failing on it). On Thu, 17 Aug 2023 at 18:43, Ekaterina Dimitrova <e.dimitr...@gmail.com> 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 <mmu...@apache.org> 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 <dri...@gmail.com> 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 >> > <e.dimitr...@gmail.com> 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 <jmcken...@apache.org> >> 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/. >> > >> >> > >> 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. I will not be available the next few days, but I can help with >> reviews when I am back. >> > >> >> > >> On Thu, 3 Aug 2023 at 17:44, Maxim Muzafarov <mmu...@apache.org> >> wrote: >> > >> >> > >> 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 < >> e.dimitr...@gmail.com> 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 <mmu...@apache.org> >> 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 < >> jeremiah.jor...@gmail.com> 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" < >> dev@cassandra.apache.org> 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 < >> jmcken...@apache.org> 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 <lewandowski.ja...@gmail.com> >> > >> >> >>> Sent: Wednesday, August 2, 2023 23:38 >> > >> >> >>> To: dev@cassandra.apache.org >> > >> >> >>> 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 < >> de...@chen-becker.org<mailto:de...@chen-becker.org>> 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 < >> jmcken...@apache.org<mailto:jmcken...@apache.org>> 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 < >> dri...@gmail.com<mailto:dri...@gmail.com>> 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 >> > >> >> >>> <e.dimitr...@gmail.com<mailto:e.dimitr...@gmail.com>> 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://urldefense.com/v3/__https://keybase.io/dchenbecker__;!!PbtH5S7Ebw!dmrZfErkoxdJW2cgt84x85sD7tNeOGjnQJ6LEdlIntSsHeTKcpEbK-kW5keI55z5pOckGINXdxUpNJFN5hs$> >> < >> 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 >> <https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!PbtH5S7Ebw!dmrZfErkoxdJW2cgt84x85sD7tNeOGjnQJ6LEdlIntSsHeTKcpEbK-kW5keI55z5pOckGINXdxUpA7_c6Go$>> >> and | >> > >> >> >>> | >> https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org >> <https://urldefense.com/v3/__https://pgp.mit.edu/pks/lookup?search=derek*40chen-becker.org__;JQ!!PbtH5S7Ebw!dmrZfErkoxdJW2cgt84x85sD7tNeOGjnQJ6LEdlIntSsHeTKcpEbK-kW5keI55z5pOckGINXdxUpIqO11GM$> >> < >> 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 >> <https://urldefense.com/v3/__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__;JSUlJSUlJSUlJSUlJSUlJSUlJSUlJSUlJSU!!PbtH5S7Ebw!dmrZfErkoxdJW2cgt84x85sD7tNeOGjnQJ6LEdlIntSsHeTKcpEbK-kW5keI55z5pOckGINXdxUpghf1fyU$>> >> | >> > >> >> >>> | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 >> 6ACC | >> > >> >> >>> >> +---------------------------------------------------------------+ >> > >> >> >>> >> > >> >> >>> >> > >> >> >>> >> > >> >> >>> >> > >> >> > >> >> >
