search

pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.64k stars 464 forks source link

mal-formatted markdown files : Multi-Line Comments for RPCs in services and fields in messages #366

Open frolickingferret445 opened 6 years ago

frolickingferret445 commented 6 years ago

I am currently trying to generate a .md markdown file from a .proto protocol buffer file. I am having issues with multi-line comments that have empty lines for spacing. This style of comment works for messages and services, but not for the fields within a message or the RPCs within a service. I looked at the examples, but they all showed only one-line comments, not multi-line comments.

I need to be able to add empty lines to the comments in the .proto file for it to successfully generate swagger documentation. Is there something I am missing? Is this a bug, or is there a reason why this is not allowed?

I have included a link to a sample .proto file and resulting .md file that reproduce this issue:

https://github.com/frolickingferret445/proto-gen-doc-error-example

Any help is appreciated.

Thanks!

frolickingferret445 commented 6 years ago

It seems that this would work if the new lines were replaced with breaks. It seems like these are being stripped away with the nobr template method in https://github.com/pseudomuto/protoc-gen-doc/blob/master/resources/markdown.tmpl#L36

Is there a reason for doing this?

SpicyLemon commented 3 weeks ago

Update: In #445, the author solved this using {{.Description | replace "\n\n" "<br><br>" | nobr}}. I didn't know about the replace filter, and that's closer to what I want. So I ended up using {{nobr .Description | replace "\n\n" "<br>"}} (instead of {{nobr .Description | p}}). I like not having the extra padding in the cells that gets added with <p> tags, and I felt that <br><br> took up more space than I'd like, and the lack of paragraph separation didn't harm reading very much.

I just solved this in our own stuff by using a custom template. I took the default template and changed all the {{nobr .Description}} entries to{{nobr .Description | p}} (5 places).

The nobr filter combines continuous lines of comments into single lines, but still puts \n\n in where there's an empty comment line. Then the p filter wraps each of those in <p> </p> and puts them all on a single line. Since it's now a single line, the tables render correctly.

A better fix might be to update nobr to do the paragraph joining on <br> (which would make me chuckle at the "nobr" name, but still makes sense). I.e. do strings.Join(paragraphs, "<br>") (instead of strings.Join(paragraphs, "\n\n")). I don't know if that breaks other things, though, so maybe it'd be better to just update the default template.

Example problem protobuf comment content:

  // DoThing does the thing.
  //
  // You can supply an other thing to make it also do that.
  // But if there's something else nonsensical, you don't have to do it.
  //
  // And this is just
  // some more comment stuff.
  rpc DoThing(DoThingReq) returns (DoThingResp)

With just nobr, that gets rendered as:

DoThing does the thing.

You can supply an other thing to make it also do that. But if there's something else nonsensical, you don't have to do it.

And this is just some more comment stuff.

It's those extra lines that break the markdown tables.

With just p, it gets rendered as:

<p>DoThing does the thing.</p><p>You can supply an other thing to make it also do that.</p><p>But if there's something else nonsensical, you don't have to do it.</p><p>And this is just</p><p>some more comment stuff.</p>

That'd fix the table problem, but makes the cell look weird because of where the paragraph breaks are in some cases. Protobuf formatters usually limit the length of comment lines, so a line break in a comment often doesn't coincide with the end of a sentence. And even if the comment line is a full sentence, it might not be a full paragraph.

With nobr ... | p, it gets rendered as:

<p>DoThing does the thing.</p><p>You can supply an other thing to make it also do that. But if there's something else nonsensical, you don't have to do it.</p><p>And this is just some more comment stuff.</p>

That fixes the table problem (one line) and also puts the paragraph tags in more natural places.

If the nobr filter were to be updated to join the paragraphs using <br> (instead of \n\n), it'd look like this:

DoThing does the thing.<br>You can supply an other thing to make it also do that. But if there's something else nonsensical, you don't have to do it.<br>And this is just some more comment stuff.

That'd also fix the tables and probably make the rows a little shorter since the <br> line break usually takes up less vertical space than what goes before/after <p>...</p>.