Enhanced Documentation?

[ehallander9591]

protobuf.js version: <6.4.2>

Enhancement Request.

Was checking out https://github.com/estan/protoc-gen-doc and looking at the results, and thought that maybe pbjs could add the comments from a .proto file to it's own generated comments

Cheers

/**
 * The type of change the published type represents
 */
enum ChangeType {
	CHG_UNKNOWN = 0;    /// An Unknown ChangeType condition
	CHG_UPSERT = 1;     /// Updated or Insert / Added
	CHG_DELETED = 2;    /// Deleted
}

could produce

                /**
                 * ChangeType enum.
                 * The type of change the published type represents
                 * @name ChangeType
                 * @memberof com.eoir.mpxs
                 * @enum {number}
                 * @property {number} CHG_UNKNOWN=0 An Unknown ChangeType condition
                 * @property {number} CHG_UPSERT=1 Updated or Insert / Added
                 * @property {number} CHG_DELETED=2 Deleted
                 */

or something like that.

<please paste the stack trace of the error if applicable>

[ehallander9591]

Then running jsdoc against the staticModule would product more complete and better documentation than what the plugin tool is producing.

[dcodeIO]

I really like the idea. Currently, the tokenizer skips over comments, though. Will have a look whether it's possible or not.

[dcodeIO]

There is probably more to do here. For reference, this is the test case:

• comments.proto input
• comments.js output

[dcodeIO]

While looking at the output of other test files, I realized that parsing all types of comments leads to a lot of nonsense for older protos, like using just commented out lines as field descriptions and stuff like that. Therefore, I decided to limit comment parsing to actual /** comment blocks for compatibility - it's also less code required to make this work.

For example, this should do what you want:

/**
 * The type of change the published type represents
 */
enum ChangeType {
	/** An Unknown ChangeType condition */
	CHG_UNKNOWN = 0;
	/** Updated or Insert / Added */
	CHG_UPSERT = 1;
	/** Deleted */
	CHG_DELETED = 2;
}

Might still look at /// comments again.

[dcodeIO]

And now also this:

/**
 * The type of change the published type represents
 */
enum ChangeType {
	CHG_UNKNOWN = 0; /// An Unknown ChangeType condition
	CHG_UPSERT = 1;  /// Updated or Insert / Added
	CHG_DELETED = 2; /// Deleted
}

[ehallander9591]

That looks pretty damn good sir.

Double Thanks