Slashes end up in the html output when using triple-slash comments

[aschrijver]

Thanks for your nice project.

I noticed a bug when using triple-slash comments ///. If you have this:

/// Hypercore Info message.
message Info {

  /// If you have a comment line, like this, that occupies multiple lines here and is
  /// long enough to also break in html, then the html output contains a single forward
  /// slash that shouldn't be there.
  optional bool uploading = 1;
  optional bool downloading = 2;
}

When using the /** ... */ style comments there are no issues, so I'm using only these now.

Versions:

• Ubuntu 16.04
• libprotoc 2.6.1
• protoc-gen-doc 0.9 (presumably, but protoc-gen-doc --version is not supported to confirm that)

[jason-fox]

According to the official protobuf specifications - *.proto files should be commented using C++ double slash comments.

In order to alter this to triple slash c# documentation comments I've used the following bash script as a preprocesing workaround - this also has the side-effect of clearing up extra slashes in the HTML output.

#!/bin/bash
#
#
# 	Adds C# style comments to a protobuf line
#
# 	Usage: ./tripleSlash.sh inputFile > outputFile


# Enable error reporting in case script fails
set +x
previousWasComment=false

if [ $# -eq 0 ]
then
    echo "No arguments supplied"
    exit 1
fi

# Read all lines - ensuring we read the final line just in case  
# the newline is missing at the end of file
# 
while IFS= read -r inputLine || [ -n "$inputLine" ]; 
do
	# Just in case the file is already C#-style document comment annotated,
	# revert any document comments ///  back to ordinary C++ comments //
	# 
	# Then convert all double slashes (C++ style) to triple slashes (C# style)
	# so they can be read in as documentation comments
	line=`echo "${inputLine}" | sed 's,///,//,' | sed 's,//,///,'`

	# Only the first line of any documentation comment needs to be triple slashed
	# Check to see if the current line is a comment
	if  [[ ${inputLine#"${inputLine%%[![:space:]]*}"} == //* ]] # "
	then
		if [[ $previousWasComment == true ]]
		then
			# If current line is a comment and the previous line was also a comment,
			# revert back to double slash
			line=`echo "${inputLine}" | sed 's,///,//,'`
		fi
		previousWasComment=true # This was a comment line - set the flag for next time
	else
		previousWasComment=false # This was not a comment line - reset the flag
	fi
	echo "${line}"
done < "$1" 

[aschrijver]

sorry, for my late reply and thanks for the elaborate explanation 👍
i am busy building innercircles, a non-profit movement for people who care :)

will have need for good .proto docgen later, but cannot spare time now..

will come back later, really like this project!

keep good work

arnold