You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@datasketches.apache.org by "tisonkun (via GitHub)" <gi...@apache.org> on 2026/08/11 02:55:54 UTC

[PR] docs: standardize public API documentation style (datasketches-rust)

tisonkun opened a new pull request, #197:
URL: https://github.com/apache/datasketches-rust/pull/197

   ## Summary
   
   - Standardize publicly reachable rustdoc summaries on third-person present tense, using forms such as `Creates`, `Updates`, and `Returns`.
   - Normalize sentence punctuation, inline-code formatting for identifiers and ranges, and `lg_k` terminology while retaining exact Rust parameter names where needed.
   - Reorder existing sections as Examples, Errors, and Panics, followed by compatibility notes; no failure-semantics sections were added.
   - Document these conventions in `CONTRIBUTING.md`.
   
   ## Scope
   
   This is a documentation-only refactor. It does not change code, public APIs, or runtime behavior.
   
   ## Validation
   
   - `cargo x check`
   - `cargo x test`
   - `cargo x lint`
   - Rustdoc JSON audit across all features for summary voice, punctuation, terminology, and section order
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: standardize public API documentation style (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #197:
URL: https://github.com/apache/datasketches-rust/pull/197#discussion_r3754950970


##########
CONTRIBUTING.md:
##########
@@ -60,6 +60,13 @@ Lint:
 cargo x lint
 ```
 
+## Public API documentation
+
+- Describe types with noun phrases and API behavior with third-person present-tense verbs such as `Creates`, `Updates`, and `Returns`.
+- End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
+- Use `lg_k` for the algorithm parameter in prose. Use a different name only when referring to an exact Rust identifier or an external serialization format.

Review Comment:
   Why is `lg_k` so special to be mentioned here?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: standardize public API documentation style (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #197:
URL: https://github.com/apache/datasketches-rust/pull/197#discussion_r3755001166


##########
CONTRIBUTING.md:
##########
@@ -60,6 +60,13 @@ Lint:
 cargo x lint
 ```
 
+## Public API documentation
+
+- Describe types with noun phrases and API behavior with third-person present-tense verbs such as `Creates`, `Updates`, and `Returns`.
+- End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
+- Use `lg_k` for the algorithm parameter in prose. Use a different name only when referring to an exact Rust identifier or an external serialization format.

Review Comment:
   Agreed. lg_k is a one-off terminology cleanup rather than a general documentation rule, so I removed this bullet from CONTRIBUTING.



##########
CONTRIBUTING.md:
##########
@@ -60,6 +60,13 @@ Lint:
 cargo x lint
 ```
 
+## Public API documentation
+
+- Describe types with noun phrases and API behavior with third-person present-tense verbs such as `Creates`, `Updates`, and `Returns`.
+- End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
+- Use `lg_k` for the algorithm parameter in prose. Use a different name only when referring to an exact Rust identifier or an external serialization format.
+- When applicable, order sections as `# Examples`, `# Errors`, and `# Panics`, followed by compatibility notes. Include only sections that describe an actual contract.

Review Comment:
   Agreed. I changed the convention to put contract sections and compatibility notes first, with Examples last, and applied that ordering throughout this PR.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: standardize public API documentation style (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on code in PR #197:
URL: https://github.com/apache/datasketches-rust/pull/197#discussion_r3754984189


##########
CONTRIBUTING.md:
##########
@@ -60,6 +60,13 @@ Lint:
 cargo x lint
 ```
 
+## Public API documentation
+
+- Describe types with noun phrases and API behavior with third-person present-tense verbs such as `Creates`, `Updates`, and `Returns`.
+- End summary sentences with punctuation, and format Rust identifiers, literals, and numeric ranges as inline code.
+- Use `lg_k` for the algorithm parameter in prose. Use a different name only when referring to an exact Rust identifier or an external serialization format.
+- When applicable, order sections as `# Examples`, `# Errors`, and `# Panics`, followed by compatibility notes. Include only sections that describe an actual contract.

Review Comment:
   I think `Examples` should go in the last position; that is, the contract first, then examles.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: standardize public API documentation style (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun merged PR #197:
URL: https://github.com/apache/datasketches-rust/pull/197


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org


Re: [PR] docs: standardize public API documentation style (datasketches-rust)

Posted by "tisonkun (via GitHub)" <gi...@apache.org>.
tisonkun commented on PR #197:
URL: https://github.com/apache/datasketches-rust/pull/197#issuecomment-5250308327

   All reviewed. The documents of `HllType` can be reverted to contain more details. But the current version focuses more on user-facing information and I think it's fair enough to do the change now until someone has a different opinion.
   
   Merging ...


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@datasketches.apache.org
For additional commands, e-mail: dev-help@datasketches.apache.org