Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Multi-line comment bug with markdown output format #274

Open
arnodel opened this issue Mar 9, 2017 · 6 comments · May be fixed by #520
Open

Multi-line comment bug with markdown output format #274

arnodel opened this issue Mar 9, 2017 · 6 comments · May be fixed by #520

Comments

@arnodel
Copy link

arnodel commented Mar 9, 2017

Hi,
I have built protoc-gen-doc from source on OSX (10.11.6) (from master, commit 97718ab) following the given steps. HTML output seems correct but markdown output has a bug with mulit-line comments where the last word on one line is concatenated to the first word on the next line. Here is a minimal example:

test.proto

syntax = "proto3";

message Foo {
  /**
   * Some
   * long
   * description
   */
  bool bar = 1;
}

After running

protoc --doc_out=markdown,test.md:. test.proto

The file test.md is as follows - the important thing is the appearance of Somelongdescription with no spaces between the words.

# Protocol Documentation
<a name="top"/>

## Table of Contents
* [test.proto](#test.proto)
 * [Foo](#Foo)
* [Scalar Value Types](#scalar-value-types)

<a name="test.proto"/>
<p align="right"><a href="#top">Top</a></p>

## test.proto



<a name="Foo"/>
### Foo


| Field | Type | Label | Description |
| ----- | ---- | ----- | ----------- |
| bar | [bool](#bool) | optional | Somelongdescription |

...
@sumancholleti
Copy link

make sure you have space in .proto, if you want it in separate line , you need to something like this

/**

  • Hello COmment in line1
  • this is in line 2
    */

@arnodel
Copy link
Author

arnodel commented Mar 13, 2017

@sumancholleti This workaround is not practical as it impairs the readability of documentation comments in the .proto file.

@FlorianWolters
Copy link

I've just played around with v0.1.0-rc and the problem still exists. The parser should work similar to documentation generators such as javadoc and doxygen, i.e. a line break without a separating blank line does not cause:

  1. a line break in the generated documentation (tested with HTML).
  2. does not concat the lines together as described by @sumancholleti (tested with Markdown)

Only two line breaks, i.e. an additional blank line should cause a line break in the output format, imho.

I've not tested it with other output formats.

Sadly the current behavior makes the tool completely unusable for me, since I have to deal with a lot of documentation.

@lucasoares
Copy link

lucasoares commented Jun 28, 2023

For me its even worse. The breakline is not being handled in markdown tables:

image

image

In both ways, the generated table is incorrect, I can't have a new line between my documentation text. @pseudomuto may you give a look? Issue since 2017 haha I will try to check if I can fix but I don't know when I will available.

@lucasoares lucasoares linked a pull request Jun 30, 2023 that will close this issue
@morapet
Copy link

morapet commented Sep 5, 2023

You can replace all new lines in you template with html line breaks

"ProtoBuiltinTypes" $ProtoBuiltinTypes) -}} | {{ regexReplaceAll "\n" $Description "${1}<br/>" }}

@ToastyKen
Copy link

ToastyKen commented Sep 19, 2023

I think @lucasoares's solution is the right one, and it'd be great if their PR could get merged. Only double newlines should be converted to <br><br>. If you convert all line breaks, then you will force the hard word wraps of long proto comments into the output HTML, which would not be ideal. Converting only double newlines is how markdown generally works.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants