Response Data docs #75
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
nevans
force-pushed
the
response-docs
branch
from
89b5328
to
1bbcfbf
Compare
|
@shugo: the reference to nevans/rdoc has been removed from this PR. I updated every single struct in
Also, please let me know what you think about my
Even with those changes, a lot of servers have had difficulty producing valid bodystructures, so I have some "foolproof" bodystructure code that I've been using for years. It was too big of a change to send along with the other parser PRs I pushed, but I think I can simplify it for a future PR. IIRC, any violation of the spec that didn't have an unambiguous or obvious alternative interpretation causes the parser to backtrack and parse the how bodystructure as a generic parenthesized list of astrings and nested lists of the same, and return that inside a BodystructUnparsable object. |
nevans
force-pushed
the
response-docs
branch
from
1bbcfbf
to
296bf46
Compare
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Document backwards-compatibility for unparsed response code data. * Document Net::IMAP#responses behavior. * Document RFC3501 codes. * List RFC5530 codes.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible. Attempt to link to mailbox attr docs, but rdoc section links are broken.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible. Expand the attr hash documentation, to provide more examples. Add more data item details from the RFCs.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible. * Link to the appropriate RFC(s).
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible.
* Move struct field docs from the class to methods inside the class. * Remove ABNF comments. * Add type information to the call-seq or the method rdoc text. * Link to the data type(s) that are returned, when possible. Add warnings to BodyTypeAttachment and BodyTypeExtension. BodyTypeText and BodyTypeMessage link to BodyTypeBasic for documentation of common fields. Link to relevant RFCs where relevant. Update formatting.
This can be used for documentation, `case` statements and pattern matching, and functionality common to all `BodyType*` structs.
nevans
force-pushed
the
response-docs
branch
from
296bf46
to
7e73b62
Compare
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.
I've converted the documentation for all of the response data structs' fields to meta-method rdoc. (I prefer the rdoc formatting for methods vs attr.) This allows us to link to the documentation for specific fields from elsewhere.
In several places, I did more than just copy the existing doecumentation to a new format. E.g:
This should be fairly complete, self-contained, and safe to merge as-is. One caveat: the MailboxList links (in bafc119) are broken. These point to the Mailbox attributes and special use attributes sections in Net::IMAP, and there's an
rdocbug that section links with spaces or special chars are intepreted as (broken) label links.I have other changes in another branch (soon-to-be PR) that simplifies working with
Response => ResponseText => ResponseCode,BodyStructureand theBodyType*classes, and makes the documented changes toResponseParserso we can removeBodyTypeExtensionandBodyTypeAttachment. Those PRs will update these docs again, but I think it's fine to merge this first rather than wait for those PRs to be complete.FYI: cherry-picks 981ea30 (to avoid conflicts later)