Implement docstrings

[emilyaherbert]

Closes #149

For the test case:

script;

/// Enum representing either a number or a string
///
/// # Examples
///
/// `NumberOrString::Number(42)`
/// `NumberOrString::String("foo")`
enum NumberOrString {
	/// The `Number` variant in `NumberOrString`
	Number: u64,
	/// The `String` variant in `NumberOrString`
	String: str[4],
}

/// Struct holding:
///
/// 1. A `value` of type `NumberOrString`
/// 2. An `address` of type `byte`
struct Data {
	/// The `value` field in `Data`
	value: NumberOrString,
	/// The `address` field in `Data`
	address: byte,
}

/// The main function that does all the things!
fn main() -> u64 {
  let mut data = Data { 
                  value: NumberOrString::Number(20),
                  address: 0b00001111,
                };

  return 20;
}

It produces vec:

{
    "struct.Data.value": [
        "/// The `value` field in `Data`",
    ],
    "fn.main": [
        "/// The main function that does all the things!",
    ],
    "enum.NumberOrString": [
        "/// Enum representing either a number or a string",
        "///",
        "/// # Examples",
        "///",
        "/// `NumberOrString::Number(42)`",
        "/// `NumberOrString::String(\"foo\")`",
    ],
    "enum.NumberOrString.String": [
        "/// The `String` variant in `NumberOrString`",
    ],
    "struct.Data.address": [
        "/// The `address` field in `Data`",
    ],
    "struct.Data": [
        "/// Struct holding:",
        "///",
        "/// 1. A `value` of type `NumberOrString`",
        "/// 2. An `address` of type `byte`",
    ],
    "enum.NumberOrString.Number": [
        "/// The `Number` variant in `NumberOrString`",
    ],
}

It doesn't actually do anything with the vec, it just kind of keeps it around for now. I suppose implementing something with it will be a seperate issue.

[sezna]

This looks really good -- I think, for the sake of @leviathanbeak's sanity and usability, we should probably remove the /// from the strings and store it as one long string instead of separate lines. That way he can ingest the documentation directly instead of doing further processing.

cc @leviathanbeak -- what do you think about this for cargo doc?

[adlerjohn]

and store it as one long string instead of separate lines

Wouldn't that result in information loss? There's cases where documentation should be in different lines (e.g. there's an inline code block).

[sezna]

and store it as one long string instead of separate lines

Wouldn't that result in information loss? There's cases where documentation should be in different lines (e.g. there's an inline code block).

We could keep newline characters, my meaning is just to not keep them as separate items in an array.

[leviathanbeak]

@sezna yeah makes sense, no need to keep the "///" just for me to clean them up - while having separate (new)lines makes sense as well. nice job @emilyaherbert

[emilyaherbert]

{
    "struct.Data.address": [
        "The `address` field in `Data`",
    ],
    "fn.main": [
        "The main function that does all the things!",
    ],
    "struct.Data.value": [
        "The `value` field in `Data`",
    ],
    "struct.Data": [
        "Struct holding:",
        "",
        "1. A `value` of type `NumberOrString`",
        "2. An `address` of type `byte`",
    ],
    "enum.NumberOrString.Number": [
        "The `Number` variant in `NumberOrString`",
    ],
    "enum.NumberOrString.String": [
        "The `String` variant in `NumberOrString`",
    ],
    "enum.NumberOrString": [
        "Enum representing either a number or a string",
        "",
        "# Examples",
        "",
        "`NumberOrString::Number(42)`",
        "`NumberOrString::String(\"foo\")`",
    ],
}

[sezna]

We could keep newline characters, my meaning is just to not keep them as separate items in an array.

Could we still do this? Just a .join("\n") is sufficient

[sezna]

approved with nits if you want to take them