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> 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> 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> >> 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> 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 and | >> | https://pgp.mit.edu/pks/lookup?search=derek%40chen-becker.org | >> | Fngrprnt: EB8A 6480 F0A3 C8EB C1E7 7F42 AFC5 AFEE 96E4 6ACC | >> +---------------------------------------------------------------+ >> >> >>
