[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17680601#comment-17680601
]
Benedict Elliott Smith edited comment on CASSANDRA-18193 at 1/25/23 12:45 PM:
------------------------------------------------------------------------------
Since this was brought up in the context of review feedback, could you please
take a bit more time to provide more detailed input, as is typical of this kind
of review request. If this is however a "nice to have" general target to aim
for, could you separate any near-term review-like asks into another ticket?
My responses all assume this is to be considered "review feedback":
{quote}all interfaces and all methods in acccord.api have API docs explaining
the requirements for the implementations
{quote}
I can certainly see some easy minor improvements here that I can make, but
since the API methods are generally quite simple and mostly documented (and the
implementation was accomplished successfully based on the existing
documentation), could you please provide detailed feedback about which
{{accord.api}} interfaces and methods you think are _inadequately_ documented,
and as a result ambiguous? I can see for instance that {{{}slice{}}},
{{{}merge{}}}, {{apply}} and {{read}} methods are not documented on every
interface, but are pretty obvious. I will ensure each method has some
documentation, but since all of the complicated APIs have quite extensive
documentation, and the others are fairly obvious, I fear that without more
direction I may not achieve a worthwhile near-term improvement.
{quote}enums and their values across the project are documented
{quote}
Again, could you please point me to enums you find unclear? I am in general
opposed to cluttering the code with redundant explanations that just say
broadly the same thing as a thing's name, just using more words.
I can see that {{Status}} (and the related {{{}SaveStatus{}}}) are complex and
not individually documented, but these states either map directly to the paper
or are carefully documented, and each of their constituent states are
documented, so that their semantics are quite clear. I am unconvinced that
documentation would materially add to their meaning, and would clutter the
class so that their relative sub-states are not as easily viewed simultaneously
(which harms interpreting their relative behaviours).
This has all passed review already, with the readers having no difficulty
understanding their meaning. So, more detail than just "all enums must be
documented" is very much required.
{quote}interfaces, abstract classes, or classes that do not inherit from
anything in the project have at least some class level explanation
{quote}
Again, this is undirected and non-specific feedback. Please provide some
detailed feedback about which classes you think are ambiguous, and that need
detailed explanations of their functionality or semantics in order to easily
understand them.
{quote}white paper in a form of an AsciiDoc or Markdown somewhere in the
project tree
{quote}
I don't think this is necessary. Eventually we may find time to translate it,
but the paper is likely to be evolved and there is no particular value in
including the current state when it is available online.
{quote}Eventually, it would really awesome if concepts from the whitepaper are
somehow referenced in the code (or vice-versa)
{quote}
I agree, and as a long term goal I hope this can be achieved, but it is not a
priority for the moment. Both the code and the white paper will be evolved in
time.
was (Author: benedict):
Since this was brought up in the context of review feedback, could you please
take a bit more time to provide more detailed input, as is typical of this kind
of review request. If this is however a "nice to have" general target to aim
for, could you separate any near-term review-like asks into another ticket?
My responses all assume this is to be considered "review feedback":
{quote}all interfaces and all methods in acccord.api have API docs explaining
the requirements for the implementations
{quote}
I can certainly see some easy minor improvements here that I can make, but
since the API methods are generally quite simple and mostly documented (and the
implementation was accomplished successfully based on the existing
documentation), could you please provide detailed feedback about which
{{accord.api}} interfaces and methods you think are _inadequately_ documented,
and as a result ambiguous? I can see for instance that {{{}slice{}}},
{{{}merge{}}}, {{apply}} and {{read}} methods are not documented on every
interface, but are pretty obvious. All of the complicated APIs have quite
extensive documentation.
I agree a general goal of improvement here is good, but without more direction
I fear it may not achieve a worthwhile near-term improvement.
{quote}enums and their values across the project are documented
{quote}
Again, could you please point me to enums you find unclear? I am in general
opposed to cluttering the code with redundant explanations that just say
broadly the same thing as a thing's name, just using more words.
I can see that {{Status}} (and the related {{{}SaveStatus{}}}) are complex and
not individually documented, but these states either map directly to the paper
or are carefully documented, and each of their constituent states are
documented, so that their semantics are quite clear. I am unconvinced that
documentation would materially add to their meaning, and would clutter the
class so that their relative sub-states are not as easily viewed simultaneously
(which harms interpreting their relative behaviours).
This has all passed review already, with the readers having no difficulty
understanding their meaning. So, more detail than just "all enums must be
documented" is very much required.
{quote}interfaces, abstract classes, or classes that do not inherit from
anything in the project have at least some class level explanation
{quote}
Again, this is undirected and non-specific feedback. Please provide some
detailed feedback about which classes you think are ambiguous, and that need
detailed explanations of their functionality or semantics in order to easily
understand them.
{quote}white paper in a form of an AsciiDoc or Markdown somewhere in the
project tree
{quote}
I don't think this is necessary. Eventually we may find time to translate it,
but the paper is likely to be evolved and there is no particular value in
including the current state when it is available online.
{quote}Eventually, it would really awesome if concepts from the whitepaper are
somehow referenced in the code (or vice-versa)
{quote}
I agree, and as a long term goal I hope this can be achieved, but it is not a
priority for the moment. Both the code and the white paper will be evolved in
time.
> Provide design and API documentation
> ------------------------------------
>
> Key: CASSANDRA-18193
> URL: https://issues.apache.org/jira/browse/CASSANDRA-18193
> Project: Cassandra
> Issue Type: Task
> Components: Accord
> Reporter: Jacek Lewandowski
> Priority: Normal
>
> Would be great if we have at minimum:
> - white paper in a form of an AsciiDoc or Markdown somewhere in the project
> tree
> - all interfaces and all methods in {{acccord.api}} have API docs explaining
> the requirements for the implementations
> - enums and their values across the project are documented
> - interfaces, abstract classes, or classes that do not inherit from anything
> in the project have at least some class level explanation
> Eventually, it would really awesome if concepts from the whitepaper are
> somehow referenced in the code (or vice-versa). It would make it much easier
> to understand the implementation and I believe it would improve reuse of this
> project for external applications
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
