{
  "$type": "site.standard.document",
  "canonicalUrl": "https://deterministic.space/machine-readable-inline-markdown-code-cocumentation.html",
  "path": "/machine-readable-inline-markdown-code-cocumentation.html",
  "publishedAt": "2016-08-17T00:00:00.000Z",
  "site": "at://did:plc:x67qh7v3fd7znbdhauc45ng3/site.standard.publication/3mjcd2t6afe25",
  "textContent": "In [Rust RFC 1713][rfc-pr-1713], a set of documentation 'tags' is proposed, to document functions in a similar fashion to e.g. JavaDoc or JSDoc. I recently [saw][swift-doc-markup] that Swift uses plain Markdown for documentation. Xcode is able to parse this and show contextual information based on it.\n\nSince Rust's [current documentation conventions][rfc-1574] already wants you to use common names for Markdown headlines to structure your code documentation, I think it would be very nice to continue in this style and use plain Markdown with specific conventions.\n\nMarkdown formatting conventions\n\nThe following sections are treated specially and are expected to be in the described format.\n\nCommon headlines\n\nThese are the common headlines from [RFC 1574][rfc-1574]:\n\nExamples\n: Must contain at least one Rust code snippet\n: Should use sub-headlines when multiple examples are given. Each sub-section should have a headline, followed by a short paragraph explaining the examples, and at least one Rust code block.\n\nPanics\n: Explains when a function panics, should always be included when panic!, assert! or similar are used/when any branch of the function can directly return !\n\nErrors\n: Explain when an error value is returned (see also \"Returns\" in the next section)\n\nSafety\n: Describes the safety requirements of this function\n\nAborts\n: Similar to panic\n\nUndefined Behavior\n: Describes for which inputs the function behavior is not defined\n\nPlatform-specific behavior\n: Describe different behavior of function or module depending on the target platform\n\nSee also\n: List of links to other pages that are relevant to this one\n: Might make use of [intra doc links] to refer to other Rust items\n\n[intra doc links]: https://github.com/rust-lang/rfcs/pull/1946\n\nSpecific machine readable sections\n\nThis is aimed at documenting functions and methods, but should also work for documenting type parameters and lifetime parameters of structs, enums, and traits.\n\nParameters\n: (always plural)\n: List of parameter names with description\n\nReturns\n: (read either as 3rd person singular form or plural \"return [values]\")\n: Plain text description\n: can be followed by a list of valid enum variants for the return type and descriptions\n: Alternatively, allow regular pattern matching syntax instead of enum variant names\n\nType parameters\n: List of generic type parameters (the T in fn foo<T>()) and description (can also be used to describe trait bounds in where clauses)\n\nLifetimes\n: (alternatively \"Lifetime parameters\")\n: List of valid lifetime identifiers (without leading ') and description\n\nList syntax\n\nAll lists mentioned above must be written like this:\n\nThat is: A Markdown list where each list items\n\n- starts with an inline code snippet containing a valid Rust identifier ($name),\n- optionally followed by a colon and a space, which is followed by valid Markdown text ($explanation, can be multi-line, but must be correct in list-item position).\n\nLints\n\nAll conventions listed above should be checked by lints.\n\nExample\n\nrust\n/// assert_eq!(fooify(\"lorem\", Foo::extract_from_global_floof_resource()).label(),\n///            Bar::with_label(\"lorem\"))\n/// \n\n[rfc-pr-1713]: https://github.com/rust-lang/rfcs/pull/1713\n[rfc-1574]: https://github.com/rust-lang/rfcs/blob/30221dc3e025eb9f8f84ccacbc9622e3a75dff5e/text/1574-more-api-documentation-conventions.md\n[swift-doc-markup]: https://developer.apple.com/library/tvos/documentation/Xcode/Reference/xcode_markup_formatting_ref/AddingMarkup.html#//apple_ref/doc/uid/TP40016497-CH3-SW1\n\n- - -\n\nPeople have been wanting to update rustdoc to use the pulldown-cmark crate instead of the currently used bindings to the hoedown library.\n\n~~It might be interesting to implement a POC for parsing the format specified above with pulldown-cmark.~~ I did just that.",
  "title": "Machine Readable Inline Markdown Code Documentation",
  "updatedAt": "2016-08-17T00:00:00.000Z"
}