Polish documentation for the queue module - #10888
Conversation
bjorng
added
team:VM
CT Test Results 2 files 100 suites 1h 10m 6s ⏱️ For more details on these failures, see this check. Results for commit 1bf2114. ♻️ This comment has been updated with latest results. To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass. See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally. Artifacts
// Erlang/OTP Github Action Bot |
garazdawi
left a comment
garazdawi
left a comment
There was a problem hiding this comment.
lgtm, just have some small suggestions.
| chk_tuple(QsA, QsB, T, X, Y, N+1). | ||
|
|
||
| doctests(_Config) -> | ||
| ct_doctest:module(queue, []). |
There was a problem hiding this comment.
| ct_doctest:module(queue, []). | |
| ct_doctest:module(queue, [{skipped_blocks, 0}]). |
There was a problem hiding this comment.
That doesn't seem to have any effect. As far as I understand, skipped blocks are examples blocks with unnumbered prompts (i.e. > instead of 1). It doesn't count functions without examples.
There was a problem hiding this comment.
it asserts that there are no untested blocks added in future updates to the docs. Making sure that we don't add any examples that should be tested that aren't because they are skipped. It is false by default, so we need to add it to all ct_doctest calls. I considered having 0 as the default, but decided against it as it would probably be surprising to most users.
We could also add an option that lists how many undocumented functions there are? Instead of returning it as a comment?
There was a problem hiding this comment.
Ok, it does complain if I add a block with an unnumbered prompt.
We could also add an option that lists how many undocumented functions there are?
Do you mean untested functions (functions without tested examples)? Yes, I would like that.
22b55df to
576c295
Compare
Ensure that the first sentence describing each function makes sense by itself when shown in the Summary part of the documentation. Add examples for all functions. Ensure that the example don't show the internal representaion of queues. While at it, get rid of old-style `catch` from the test sutie, remove comments for documented functions, remove out-commented code, and do some other minor clean ups.
576c295 to
1bf2114
Compare
3 participants
Ensure that the first sentence describing each function makes sense by itself when shown in the Summary part of the documentation.
Add examples for all functions. Ensure that the example don't show the internal representaion of queues.
While at it, get rid of old-style
catchfrom the test sutie, remove comments for documented functions, remove out-commented code, and do some other minor clean ups.