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!c_gIN2FFX7lIgL895Jhw3GdROOCiOucxfyyswuwrPEcr7LfwnOiLQcAiVHMHpnjnwbNPSA3PgK8GN_z2fJ0$> >> < >> 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!c_gIN2FFX7lIgL895Jhw3GdROOCiOucxfyyswuwrPEcr7LfwnOiLQcAiVHMHpnjnwbNPSA3PgK8GBVFbl8Y$>> >> 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!c_gIN2FFX7lIgL895Jhw3GdROOCiOucxfyyswuwrPEcr7LfwnOiLQcAiVHMHpnjnwbNPSA3PgK8GPMRhwFE$> >> < >> 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!c_gIN2FFX7lIgL895Jhw3GdROOCiOucxfyyswuwrPEcr7LfwnOiLQcAiVHMHpnjnwbNPSA3PgK8GpMgG0gs$>> >> | >> | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | >> +---------------------------------------------------------------+ >> >> >> >> >>
