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

Enhanced Documentation? #640

Closed
ehallander9591 opened this issue Jan 12, 2017 · 6 comments
Closed

Enhanced Documentation? #640

ehallander9591 opened this issue Jan 12, 2017 · 6 comments

Comments

@ehallander9591
Copy link

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
Copy link
Author

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

@dcodeIO
Copy link
Member

dcodeIO commented Jan 12, 2017

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

dcodeIO added a commit that referenced this issue Jan 12, 2017
@dcodeIO
Copy link
Member

dcodeIO commented Jan 12, 2017

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

dcodeIO added a commit that referenced this issue Jan 12, 2017
…s because old protos may generate a lot of nonsense otherwise, see #640
@dcodeIO
Copy link
Member

dcodeIO commented Jan 12, 2017

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 added a commit that referenced this issue Jan 13, 2017
@dcodeIO
Copy link
Member

dcodeIO commented Jan 13, 2017

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
Copy link
Author

That looks pretty damn good sir.

Double Thanks

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

No branches or pull requests

2 participants