More review updates

 - Added some additional sample content
 - Clarified "equivalent" types with respect to these guidelines
 - Clarified line break usage
 - Clarified when a horizontal rule (`<hr>`) tag is appropriate
 - Added additional clarification for paragraph breaks
 - Added guideline for non-API comments using "line oriented" (`//`)
   style comments.
 - Added a user story related to smart contract requirements.

Signed-off-by: Joseph Sinclair <[email protected]>

HIP/hip-1037.md

@@ -9,7 +9,7 @@ needs-council-approval: Yes
 status: Review
 created: 2024-08-09
 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/1037
-updated: 2024-10-09
+updated: 2024-11-06
 ---
 
 ## Abstract
@@ -56,6 +56,10 @@ reduces the inevitable "drift" between functional API and API specification.
 - As an Hedera software contributor I want to have clear and accurate
   specification for all Hedera APIs so that I can confidently implement changes
   to Hedera-led software.
+- As a dApp developer that receives bytes or is expected to parse, produce, or
+  process bytes representing a HAPI protobuf message I want to have a clear
+  specification of the structure and implications of the corresponding proto
+  messages to understand how to correctly parse them.
 
 ## Specification
 The core of this HIP is

assets/hip-1037/Specification-Format-Style-Guidelines.md

@@ -13,11 +13,20 @@
      comment boxes are limited to roughly 80 characters width. The primary
      "code" interaction with proto files and markdown files is in review.
      Also, some markdown processors struggle with longer lines.
+- Use HTML tags where appropriate, but stick to markdown as much as possible.
 - Use blank lines (with `*` prefix) for paragraph breaks in message or
   enum declarations, regardless of where defined.
    - Use `<p>` tags for _fields_, and _no_ "empty" lines (it breaks the tables).
-- Use HTML tags where appropriate, but stick to markdown as much as possible.
-- Use correct US-English spelling and grammar to the maximum extent possible.
+   - For messages (including `enum` or `service` messages), we prefer to use
+     blank lines exclusively, and _not_ use a `<p>` tag.
+- We use line breaks (`<br/>`) in several areas of the specification text.
+  All such line breaks should be placed at the _end_ of the prior line, and
+  should not be placed alone on a line, in the middle of a line, or at the
+  beginning of a line.
+- Certain elements (headings, code blocks, lists, etc...) are "block" elements
+  in markdown and HTML.  Such elements _should not_ be followed by either
+  a break (`<br/>`) or paragraph (`<p>`) tag (or equivalent markdown).
+- Use formal US-English spelling and grammar to the maximum extent possible.
    - Write proper and complete sentences, avoid partial sentences and
      unnecessary abbreviations.
    - Do not use partial words (e.g. instead of "spec" write "specification").
@@ -26,10 +35,23 @@
         but "HCS" may be used thereafter.
       - Extremely common acronyms (e.g. RAM or LASER) do not need
         to be expanded.
+
+#### Specification Equivalency
+For the purposes of specification document comments, _only_, the following
+protocol buffer "types" are considered equivalent.
+- Message
+   - `service`
+   - `enum`
+- Field
+   - `rpc`
+Equivalent types require equivalent specification, so a `service` should be
+specified using the same guidelines as a `message` or `enum`.  A `rpc` should
+be specified using the same guidelines as a "field".
+
 ### Description
-- First line of each document block is "what is this", and should be a single
-  sentence.  Examples: "An identifier for an account." or "A `tokenTransfer`
-  transaction request body.".
+- The first line of each document block is "what is this", and should be a
+  single sentence.  Examples: "An identifier for an account." or
+  "A `tokenTransfer` transaction request body.".
    - Avoid "this is a thing" (or shorter "thing") type sentences,
      write "A thing" instead.
       - This applies for the _first sentence_ only, **not** elsewhere.
@@ -39,20 +61,23 @@
      description or requirements, not here.
       - A good rule of thumb is that if this first sentence exceeds 60
         characters, then it is trying to describe too much.
-- Include a line break (`<br/>`) after the first line, then a brief description,
-  if appropriate.
-   - Not every field needs additional description, but _every_ `message` does.
-   - Descriptions may be detailed, but should not include internal
-     implementation details or requirements. The description _should_ be
-     detailed enough to explain to an external contributor what the
-     message or field contains, where it fits within the overall network
-     system, and why it is needed.
-      - This is a long-term goal; we have a long way to go to get to this
-        level of description. Every PR to change `.proto` files should seek
-        to improve the documentation for that file.
-   - Avoid describing what must, should, must not, or should not be
-     sent, or how the field values affect output. Those items belong in the
-     _requirements_, instead.
+- An optional description _may_ be added to any field or message.
+   - Include a line break (`<br/>`) after the first line, then a brief
+     description, if appropriate.
+      - Not every field needs additional description,
+        but nearly all `message` blocks do.
+      - Descriptions may be detailed, but should not include internal
+        implementation details or requirements. The description _should_ be
+        detailed enough to explain to an external contributor what the
+        message or field contains, where it fits within the overall network
+        system, and why it is needed.
+         - This is a long-term goal; we have a long way to go to get to this
+           level of description. Every PR to change `.proto` files should seek
+           to improve the documentation for that file.
+      - Avoid describing what must, should, must not, or should not be
+        sent, or how the field values affect output. Those items belong in the
+        _requirements_, instead.
+
 ### Requirements
 - After a paragraph break (a blank line for messages), one requirement per
   line. Use break tags at the end of each requirement except the last.
@@ -81,17 +106,39 @@
      is not only acceptable, but often recommended.
    - Well written specification tends to be much more short and clipped
      sentences than "normal" prose. Some describe the flow as "staccato".
+- Required and Optional fields
+   - The default state for any field is "optional", and all required fields
+     should be specified as `REQUIRED`. If the presence or absence of a field
+     must be clear _separate_ from the default value of that field, that field
+     should use proto3 "explicit presence" and be marked with
+     the `optional` keyword.
 - Add another blank line after requirements for `message` documents only.
+
 ### Other elements
 - Each message that represents a transaction body **must** document the
   Block Stream effects with a heading `### Block Stream Effects`.
 - General notes go last, for `message` only, with a heading
   `#### Additional Notes`.
+- There are cases where description text for a message or field is
+  exceptionally detailed. In these cases it _may_ be appropriate to
+  separate broad categories of information with a single horizontal line
+  (i.e. an `<hr>` tag, `---` in markdown). These cases _should_ be quite
+  rare, however; we prefer to avoid the need for such large blocks of
+  specification text.
+- Line oriented comments (i.e. lines prefixed with `//`) may be used for
+  any comments needed in a proto file that are not intended for API
+  specification.  Examples include explaining an `oneof` block, or describing
+  why a particular field number or name is reserved.
+
 ## Content Guidelines
 ### General `proto` File Guidelines
 - Protocol buffers are compiled for the `hedera-services` codebase using a
   custom processor 'PBJ'. While no other entity is required to use `PBJ`, all
-  protocol buffer files MUST be compatible with `PBJ` processing.
+  Hiero protocol buffer files MUST be compatible with `PBJ` processing.<br/>
+  Currently, this requires implementing the proposed changes in a branch
+  on the `hedera-protobufs` repository, and running the integration test
+  sub-project of the `PBJ` project.
+
 ### Field Type Guidelines
 - There are some negative patterns present in existing `proto` files.  These
   SHOULD NOT be replicated in new files, when possible.
@@ -110,6 +157,7 @@
       - One exception here is forward compatibility, as implemented in the
         `PBJ` processor, which is supported in selected scenarios where
         deterministic behavior is not strictly required.
+
 ### Package Directive Guidelines
 - There are some negative patterns present in existing `proto` files.  These
   SHOULD NOT be replicated in new files, when possible.
@@ -131,7 +179,63 @@
         then use the full package prefix when referring to those messages.
    - The "namespace" behavior of package names is not well supported by PBJ at
      this time, so packages must be fully specified whenever used.
+
 ## Examples
+### General Samples
+```protobuf
+/**
+ * A selection of positive and negative examples
+ *
+ * ## Summary and optional description.
+ * A simple Summary.<br/>
+ * This example shows recommended structure of summary line and detail
+ * description, including line length limits.
+ *
+ * ## An example for line break placement.
+ * text ending in a break.<br/>
+ * is generally easier to read than
+ * <br/>text starting with a break or
+ * text that contains<br/>a line break mid-line.
+ */
+message SampleMessage {
+    // OneOf does not become an element in the final protobuf, so any
+    // description needed for oneof blocks must be in "code" comments.
+    // Such "code" comments are permitted anywhere a comment is permitted,
+    // but writers should be aware that these comments are not processed and
+    // remain local to the proto file.
+    oneof samples {
+        // We may present "code" level comments, that are not API specification
+        // wherever needed and appropriate. These comments are not processed
+        // into documentation, and should be used for information specific to
+        // the "code" of the protocol buffer definitions, not the API that
+        // those protocol buffers represent.
+        /**
+         * A sample 32-bit integer field.
+         * <p>
+         * This block MUST NOT contain a blank line, as fields are presented
+         * using tables in markdown, so we use a paragraph tag instead.<br/>
+         * We SHALL separate requirements with a single `<br/>` tag as used
+         * at the end of the line above.
+         * <p>
+         * ### Headings in fields
+         * We MAY use headings in fields, but it is important to note
+         * that Javadoc's exceptionally strict view of headings means that
+         * headings in fields MAY NOT be rendered correctly and MAY cause
+         * javadoc errors for "out of order" headings.
+         */
+        int32 field_one = 1;
+
+        // This field does not require description or specific requirements
+        // so those are not present. Lack of requirements is very rare indeed,
+        // so most fields should have a bit more than we see here.
+        /**
+         * A simple unsigned 64-bit integer field.
+         */
+        uint64 field_two = 2;
+    }
+}
+```
+
 ### A Message Example
 ```protobuf
 /**
@@ -160,6 +264,7 @@
  * Node identifiers SHALL NOT be reused.
  */
 ```
+
 ### A Field Example
 ```protobuf
     /**
@@ -184,6 +289,7 @@
      * MUST NOT supply both values for the same endpoint.
      */
 ```
+
 ### An Enum Example
 Note that this example is _all_ description, there are no requirements
 listed.  This is unusual, but does occur.
@@ -213,6 +319,7 @@ listed.  This is unusual, but does occur.
  * of the `StateChange`.`state_id` field.
  */
 ```
+
 ### A Complex Message Example
 Note the added block for the "Alias" detail, which specifies some complex
 behavior that has, historically, caused much confusion.