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://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 | >> >>> +---------------------------------------------------------------+ >> >>> >> >>> >> >>> >> >>>
