[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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
