;mailto: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
om for tweaking this if one wishes.
From: Ekaterina Dimitrova
Sent: Monday, August 21, 2023 20:05
To: dev@cassandra.apache.org
Subject: Re: [DISCUSSION] Shall we remove ant javadoc task?
NetApp Security WARNING: This is an external email. Do not clic
dra 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 any
ving 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.
>> > >> >> >
>> > >>
g 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 startin
he 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
, 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.
>> >> >>
>>
> >> >> On Thu, Aug 3, 2023 at 4:35 AM Josh McKenzie
> wrote:
> >> >>>
> >> >>> If anything, the codebase could use a little more
> package/class/method markup in some places
> >> >>>
> >> >>> I a
h 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
>> >>
>>
> >> >>> 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
gt;> >>> :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 fi
t. 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
&g
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 e
nd 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 ...
>>
>> ________
cing
> it but what to do with what is already there ...
>
>
> From: Jacek Lewandowski
> 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.
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.
>
>
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
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
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
I second what Josh said and confirm we were talking only about the task, no
one is going to remove javadoc from the source code and I totally encourage
people to continue documenting the code
On Wed, 2 Aug 2023 at 15:30, Josh McKenzie wrote:
> most people are not looking at Javadoc when working
> 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
+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 wrote:
> I don't think even if it works anyone is going to use the output, so
> I'm
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
wrote:
>
> Hi everyone,
> We were looking into a user report around our ant javadoc task recently.
> That made us realize it is
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
24 matches
Mail list logo
