Net::IMAP Client docs #74
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This was referenced Nov 21, 2022
|
@shugo: the reference to |
nevans
force-pushed
the
client-docs
branch
2 times, most recently
from
70d9af7 to
d5d4271
Compare
* Escape some text that shouldn't be linked, e.g. IMAP. * Link some text that should be linked: * removing "+" to let classes link * Remove `Net::IMAP::` prefix from response data class names. The redundant prefix breaks up the reading flow of the text. Examples will still use fully-qualified names, and readers should generally be able to see that the classes/modules are in Net::IMAP, from context. * Add headings and convert text to headings. * Reduce headings inside method docs to h5 (call-seq renders like h4). * Add <tt> or "+" to code or verbatim text. * To match the tweaks to rdoc's darkfish template, convert definition lists to "note" vs "label" style lists for table vs lists. * Add ">>>" with <em> to highlight important "aside" notices. * Add :nodoc: to ResponseErrors.
* Document capabilities at the class-level, linking to #capability for details. * Add "Basic IMAP4rev1 capabilities" and "Using IMAP4rev1 extensions" sections to the #capability rdoc. * Add relevant capabilities to the rdoc for every command extension. * Update existing capability docs to the same consistent format. * Add TODO comment for unsupported LIST-EXTENDED
Every IMAP command method now links to the RFC section that defines it.
There are a lot of IMAP commands! This makes it easier to navigate between them. Hopefully this makes it easier to learn the IMAP4rev1 protocol and its extensions, as well.
* Link to UIDPlusData for commands that can return it: `#append`, `#copy`, and `#move` * Update `#uid_expunge` to avoid "UID set", which has slightly different semantics from "sequence set of UIDs".
* Add paragraph to class-level docs, about expunge messages. * Add explanation to #noop docs, explaining EXPUNGE responses * Update #uid_expunge docs with method link instead of command name.
nevans
force-pushed
the
client-docs
branch
4 times, most recently
from
e2fddbc to
07b1e8b
Compare
The documentation on these methods is meant to complement a new SASL::Authenticator base class and new documentation on each of the individual authenticator classes. See #78 and #82. That base class is added in another PR (#78), but the documentation for these methods can be updated without it. Also, somehow I misremembered `LOGINDISABLED`: it only applies to `LOGIN`, not `AUTHENTICATE`! This fixes that error.
Add a note about the implicit UID message data item.
Makes it just a little bit simpler.
This "What's here?" section is based on the new documentation style for many core ruby classes. It isn't purely a list of methods; paragraphs of explanatory text are interspersed. *Many* "TODO" comments are added too, hidden from rdoc by `--` and `++`.
Without resetting to the default section, code that's loaded later may be documented in the wrong place
|
@shugo I've updated this since the last time you looked at it... sorry if the rebasing makes it hard to see the differences! I tried to make each individual commit reviewable on its own. Let me know if you have any concerns with merging it. |
|
@BurdetteLamar Since you've been doing so much documentation for core and stdlib, I'm curious if you have any thoughts on this (the latest version is rendered here: https://nevans.github.io/net-imap). This is a big PR, so I understand if you don't have time for it any time soon! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a draft of my rdoc changes to the Net::IMAP class. It cherry-picks from several other PRs:
I also made several PRs to ruby/rdoc for the 6.5.0 release, and I think they make a big difference to how this renders!
The output of
rake rdoccan be viewed here: https://nevans.github.io/net-imap/Net/IMAP.htmlSome of my documentation changes were removed from this branch, because they will be obsoleted soon (I hope!).