Clean up json schema descriptions and generated documentation (#311)

The json schema contained several spurious space, astrix and other bit
of text. Removing these makes the documentation much easier to read.

Author: mpkorstanje

codegen/generators/java.rb

@@ -15,7 +15,9 @@ def format_description(raw_description, indent_string: '')
         .split("\n")
         .map(&:strip)
         .reject { |line| line == '*' }
-        .map { |line| " * #{line}".rstrip }
+        .map { |line| line.rstrip }
+        .map { |line| line.empty? ? "<p>" : line }
+        .map { |line| " * #{line}"}
         .join("\n#{indent_string}")
     end
 

codegen/templates/java.java.erb

@@ -10,10 +10,9 @@ import static java.util.Collections.unmodifiableList;
 import static java.util.Objects.requireNonNull;
 
 /**
- * Represents the <%= class_name(key) %> message in Cucumber's message protocol
- * @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
+ * Represents the <%= class_name(key) %> message in <a href=https://github.com/cucumber/messages>Cucumber's message protocol</a>
  <%- unless (schema['description'] || []).empty? -%>
- *
+ * <p>
 <%= format_description(schema['description'], indent_string: '') %>
 <%- end -%>
  */

cpp/include/messages/cucumber/messages/attachment.hpp

@@ -18,7 +18,7 @@ using json = nlohmann::json;
 // Represents the Attachment message in Cucumber's message protocol
 // @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
 //
-// //// Attachments (parse errors, execution errors, screenshots, links...)
+// Attachments (parse errors, execution errors, screenshots, links...)
 //
 // An attachment represents any kind of data associated with a line in a
 // [Source](#io.cucumber.messages.Source) file. It can be used for:

cpp/include/messages/cucumber/messages/envelope.hpp

@@ -34,13 +34,6 @@ using json = nlohmann::json;
 // Represents the Envelope message in Cucumber's message protocol
 // @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
 //
-// When removing a field, replace it with reserved, rather than deleting the line.
-// When adding a field, add it to the end and increment the number by one.
-// See https://developers.google.com/protocol-buffers/docs/proto#updating for details
-//
-// All the messages that are passed between different components/processes are Envelope
-// messages.
-//
 // Generated code
 
 struct envelope

cpp/include/messages/cucumber/messages/pickle.hpp

@@ -17,8 +17,6 @@ using json = nlohmann::json;
 // Represents the Pickle message in Cucumber's message protocol
 // @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
 //
-// //// Pickles
-//
 // A `Pickle` represents a template for a `TestCase`. It is typically derived
 // from another format, such as [GherkinDocument](#io.cucumber.messages.GherkinDocument).
 // In the future a `Pickle` may be derived from other formats such as Markdown or

cpp/include/messages/cucumber/messages/source.hpp

@@ -16,8 +16,6 @@ using json = nlohmann::json;
 // Represents the Source message in Cucumber's message protocol
 // @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
 //
-// //// Source
-//
 // A source file, typically a Gherkin document or Java/Ruby/JavaScript source code
 //
 // Generated code

cpp/include/messages/cucumber/messages/test_case.hpp

@@ -16,8 +16,6 @@ using json = nlohmann::json;
 // Represents the TestCase message in Cucumber's message protocol
 // @see <a href=https://github.com/cucumber/messages>Github - Cucumber - Messages</a>
 //
-// //// TestCases
-//
 // A `TestCase` contains a sequence of `TestStep`s.
 //
 // Generated code

dotnet/Cucumber.Messages/generated/Attachment.cs

@@ -13,7 +13,7 @@ namespace Io.Cucumber.Messages.Types;
  * Represents the Attachment message in Cucumber's message protocol
  * @see <a href="https://github.com/cucumber/messages" >Github - Cucumber - Messages</a>
  *
- * //// Attachments (parse errors, execution errors, screenshots, links...)
+ * Attachments (parse errors, execution errors, screenshots, links...)
  *
  * An attachment represents any kind of data associated with a line in a
  * [Source](#io.cucumber.messages.Source) file. It can be used for:

dotnet/Cucumber.Messages/generated/Envelope.cs

@@ -12,13 +12,6 @@ namespace Io.Cucumber.Messages.Types;
 /**
  * Represents the Envelope message in Cucumber's message protocol
  * @see <a href="https://github.com/cucumber/messages" >Github - Cucumber - Messages</a>
- *
- * When removing a field, replace it with reserved, rather than deleting the line.
- * When adding a field, add it to the end and increment the number by one.
- * See https://developers.google.com/protocol-buffers/docs/proto#updating for details
- *
- * All the messages that are passed between different components/processes are Envelope
- * messages.
  */
 
 public sealed class Envelope 

dotnet/Cucumber.Messages/generated/Pickle.cs

@@ -13,8 +13,6 @@ namespace Io.Cucumber.Messages.Types;
  * Represents the Pickle message in Cucumber's message protocol
  * @see <a href="https://github.com/cucumber/messages" >Github - Cucumber - Messages</a>
  *
- * //// Pickles
- *
  * A `Pickle` represents a template for a `TestCase`. It is typically derived
  * from another format, such as [GherkinDocument](#io.cucumber.messages.GherkinDocument).
  * In the future a `Pickle` may be derived from other formats such as Markdown or