[
https://issues.apache.org/jira/browse/CASSANDRA-18193?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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: [email protected]
For additional commands, e-mail: [email protected]
