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

Comments

Projects
None yet
2 participants
@ehallander9591

ehallander9591 commented Jan 12, 2017

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

This comment has been minimized.

ehallander9591 commented Jan 12, 2017

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

@dcodeIO

This comment has been minimized.

Owner

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 dcodeIO added the enhancement label Jan 12, 2017

dcodeIO added a commit that referenced this issue Jan 12, 2017

New: Now also parses comments, sets them on reflected objects and re-…
…uses them when generating static code, see #640
@dcodeIO

This comment has been minimized.

Owner

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

Other: Restrict comment parsing for static code to explicit /**-block…
…s because old protos may generate a lot of nonsense otherwise, see #640

dcodeIO added a commit that referenced this issue Jan 12, 2017

@dcodeIO

This comment has been minimized.

Owner

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

This comment has been minimized.

Owner

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

This comment has been minimized.

ehallander9591 commented Jan 13, 2017

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