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