Many many documentation updates #77
Conversation
Gemfile
Outdated
| source "https://rubygems.org" | ||
|
|
||
| gemspec | ||
|
|
||
| gem "rake" | ||
| gem "test-unit" | ||
|
|
||
| gem "rdoc", github: "nevans/rdoc", branch: "darkfish-combine-call-seq-div" |
There was a problem hiding this comment.
I wouldn't like to add dependency outside ruby org.
Would you merge rdoc changes before merging this PR?
There was a problem hiding this comment.
I agree. That shouldn't be merged into master it is. And that rdoc fork probably needs some more work before it makes a good PR.
I'd forgotten about this aspect when I based all of my other PRs on it. I'll split the forked dependancy into another commit (for my own testing) and I'll post the rendered results somewhere. But I'll remove that fork from all of these PRs.
Everything still works with the latest rdoc release, it just doesn't look as nice (IMO). It's hard to read a class's Table of Contents when there's no nesting (h1-h4) and it's no good to use headings inside method docs unless there's more visual separation between each method.
|
@shugo I made two PRs for ruby/rdoc: ruby/rdoc#941 and ruby/rdoc#942. To demonstrate, I pushed a version with all of my rdoc updates here: https://nevans.github.io/net-imap/Net/IMAP.html. |
* 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.
These two pieces of documentation are meant to complement a new SASL::Authenticator base class and new documentation on each of the individual authenticator classes. That base class is added in another PR, but the documentation for these can be updated without it.
Add a note about the implicit UID message data item.
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 also added, hidden from rdoc by `--` and `++`.
This is a meta-PR, combining/merging/cherry-picking documentation updates from:
BodyStructuremixin)This branch provides a single stream of commits, without merge branching or conflicts.
I tried to keep the changes to only rdoc updates. But a few other minor code changes were pulled in as well.