Convert proto markdown to language-specific doc format in all languages

[garrettjonesgoogle]

• Java
• PHP
• Node.js
• Ruby
• Python
• Go
• C#

[bjwatson]

Related PRs for Python:

• https://github.com/googleapis/toolkit/issues/222
• [Python] Sphinx cannot handle indentation in proto comments #402

Per @geigerj:

See also

https://github.com/googleapis/toolkit/blob/master/src/main/java/com/google/api/codegen/CommentPatterns.java

and

https://github.com/googleapis/toolkit/blob/master/src/main/java/com/google/api/codegen/py/PythonSphinxCommentFixer.java

for what Python does here. As discussed offline it would eventually be good to get a proper Markdown processor hooked up to this, like what we have internally.

[pongad]

According to an internal wiki, all docs should conform to https://github.com/sirthias/pegdown (Apache licensed). Might be possible to just use it.

[jskeet]

As I've noted internally, I would much prefer that a lot of this work is done in protoc. Without that, all the generated Javadoc for Java protos and ditto the XML documentation for C# will end up still being done in Markdown.

[chrisdunelm]

Not necessary in C#. The C# documentation processors handle markdown fine.

[jskeet]

@chrisdunelm: Well, sort of. docfx does, but Visual Studio doesn't (for Intellisense) - and we don't resolve all the inter-proto references etc. It would definitely be better if we could generate idiomatic XML documentation, IMO.

[chrisdunelm]

OK, marking this as not done for C# again ;)

[miraleung]

Looks like this is fixed for Java, and most other languages (save PHP) have migrated to microgenerators. Closing as obsolete.