[jira] [Commented] (CASSANDRA-18193) Provide design and API documentation
[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17681389#comment-17681389
]
Henrik Ingo commented on CASSANDRA-18193:
-
I spent some hours on Wednesday high level eyeballing the diff against G*
trunk, to form my own opinion of what I see. I might post something about that
next week, but for now I just wanted to share a by-product that I found and
according to Benedict could be something you want to uncomment before the merge?
https://github.com/apache/cassandra/blob/cep-15-accord/src/java/org/apache/cassandra/dht/Murmur3Partitioner.java#L240-L255
> 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: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-18193) Provide design and API documentation
[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17680955#comment-17680955
]
Benedict Elliott Smith commented on CASSANDRA-18193:
bq. What I don't agree with is the bar for what needs to be documented is by
the existing reviewers
The only feedback I want to see about documentation is precisely that, feedback
from a _reviewer_ who has invested some time trying to understand the code with
a view to contributing to it, with _specific_ clarifying remarks that would
help them. This is the standard target of our documentation.
bq. would you mind ranking where you value comments being added please.
Ranking remains a drive-by low effort contribution, and not particularly
actionable in my opinion, though I intend to time box some general
documentation improvements that look helpful to me, and I will use any ranking
to guide my time investment. I do not consider it directly actionable review
feedback, however.
Review involves some proper investment, with specific feedback about how
clarity can be improved. Better would be to open an empty PR you can use to
annotate the codebase with such feedback.
> 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: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-18193) Provide design and API documentation
[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17680953#comment-17680953
]
Michael Semb Wever commented on CASSANDRA-18193:
I agree with [~benedict]'s statement. We don't want every method and enum value
commented. (The design and the naming should make as much as possible
intuitive, the suggestion to cross-reference to the whitepaper was very good
for this reason.) Comments on whatever is not intuitive, particularly that
helping to understand contract and intent, is valuable. What I don't agree with
is the bar for what needs to be documented is by the existing reviewers (who
have already invested a lot of time into understanding it). IMHO it needs to be
documented with the new reader in mind. [~jlewandowski], would you mind ranking
where you value comments being added please.
> 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: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
[jira] [Commented] (CASSANDRA-18193) Provide design and API documentation
[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=17680601#comment-17680601
]
Benedict Elliott Smith commented on CASSANDRA-18193:
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: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
