Add to support /// and //! syntax for add doc comment for rules.

[huacnlee]

Resolve #748

For example:

//! A parser for JSON file.

/// Matches object, e.g.: `{ "foo": "bar" }`
object = { "{" ~ pair ~ ("," ~ pair)* ~ "}" | "{" ~ "}" }

should generate:

/// A parser for JSON file.
enum Rule {
    /// Matches object, e.g.: `{ "foo": "bar" }`
    object,
}

[tomtau]

great work! sadly, it looks like it's a semver breaking change:

Checking pest_meta
    Checking <unknown> v2.5.0 -> v2.5.2 (patch change)
   Completed [   0.141s] 33 checks; 31 passed, 2 failed, 0 unnecessary

--- failure constructible_struct_adds_field: externally-constructible struct adds field ---

Description:
A pub struct constructible with a struct literal has a new pub field. Existing struct literals must be updated to include the new field.
        ref: https://doc.rust-lang.org/reference/expressions/struct-expr.html
       impl: https://github.com/obi1kenobi/cargo-semver-check/tree/v0.15.2/src/queries/constructible_struct_adds_field.ron

Failed in:
  field Rule.comments in meta/src/ast.rs:22
  field ParserRule.comments in meta/src/parser.rs:55
  field OptimizedRule.comments in meta/src/optimizer/mod.rs:105

--- failure enum_variant_added: enum variant added on exhaustive enum ---

Description:
A publicly-visible enum without #[non_exhaustive] has a new variant.
        ref: https://doc.rust-lang.org/cargo/reference/semver.html#enum-variant-new
       impl: https://github.com/obi1kenobi/cargo-semver-check/tree/v0.15.2/src/queries/enum_variant_added.ron

Failed in:
  variant Expr:LineDoc in meta/src/ast.rs:93
  variant ParserExpr:LineDoc in meta/src/parser.rs:171
  variant OptimizedExpr:LineDoc in meta/src/optimizer/mod.rs:140
       Final [   0.161s] semver requires new major version: 2 major and 0 minor checks failed

not sure if it's possible to do in a non-breaking way (e.g. under a feature flag)... maybe mark that enum #[non_exhaustive] and make that comments field private (instead of public)?

[huacnlee]

Looks like we can't do it without the breaking changes.

We must add comments fields into Rule, ParserRule and OptimizedRule struct for storage the parsed comment strings. There no other way to store them.

---

Expr::LineDoc, ParserExpr::LineDoc and OptimizedExpr::LineDoc I have removed, it not need.

[huacnlee]

This because of themod generator is not public.

So I changed it to pub(crate).

[huacnlee]

@tomtau I have rewrite the implementation without make breaking changes.

[tomtau]

awesome work if it was made non-semver breaking! I'll have a look at in more detail hopefully soon

[tomtau]

maybe it'll be good to "dogfood" this change in the meta grammar and use it to add doc comments, but that could be done in a follow up

[tomtau]

I could possibly do that in a follow up PR

[tomtau]

the non-breaking version seems all right, but if possible, could DocComment hide its internal fields (for a better "encapsulation") ?

[tomtau]

#770 was merged -- could you rebase on top of the latest master?

[tomtau]

lgtm, just a small nit about the string construction, but ok to merge