Idea: dartdoc formatter/presubmit check

[matanlurey]

Similar to dart_style, we have some style requirements for dart documentation, i.e.

/// Represents a `Foo` object.
///
/// ## Example
///     new Foo(...)
class Foo {}

Ideas:

• [ ] Should pass a markdown check/valid markdown.
• [ ] Require a single-standalone line in public APIs.
• [ ] Prevent use of /// outside of public APIs.
• [ ] Always format Example as ## Example
• [ ] Ensure that Dart code is interpreted/wrapped for markdown

It's possible this belongs in the linter package.

/cc @pq @bwilkerson @srawlins

[srawlins]

I'm pretty sure there is no such thing as non valid markdown. This is all "valid" markdown:

######### what kind of a header is this?

_italicized... or... no? we're done?

[starts as a link](and kind of fizzles out.

I like the 2nd and 3rd ideas a lot. The 5th is also very tricky...

I like the idea of an opt-in linter rule.

[sethladd]

Nice! (not sure where it belongs, but I like lints for doc comments)

[matanlurey]

Internally there is some sort of MD lint for g3doc - I imagine something similar? @srawlins

[devoncarew]

I would vote for support for this in the linter - the lints will show up in all the right places then, and not just visible when you generate docs.

[pq]

I would vote for support for this in the linter

👍

In a similar vein we added simple validation of regexps:

http://dart-lang.github.io/linter/lints/valid_regexps.html

This would be a little trickier but add lots of value.