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