-
Notifications
You must be signed in to change notification settings - Fork 6
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
Params and Returns missing 'comment' field #1
Comments
Some thoughts:
Perhaps? Where
So, line breaking?
At which point, perhaps "real" comments make more sense
|
Hi there, It's an interesting idea, but the grammar implications seem interesting. But my main thought is that if you need that level of detail in your API documentation you probably want to use request/response structs, which you can comment per-field already. Positional parameters aren't as flexible (can't be optional, for example). Adding new positional parameters over time will also break backwards compatibility, whereas adding optional struct fields does not. I'll leave this ticket open and see if anyone else wants to chime in. If you have interest in editing the parser, I'd accept a pull request for this, provided it's fully backwards compatible (I have a bunch of IDL files I can verify that against). -- James |
While working on (https://github.com/chuyskywalker/reverse-php-barrister-idl) I came across the dilemma that, within interfaces, there is no room for comments on parameters and return values. As an example, in PHP:
Corresponding IDL:
Nearly everything in the PHP snippet is codified within the IDL/JSON except for the return value explanation and comments on parameters.
The comment on return value is probably more important as params should generally be pretty clear via their variable names.
Not really sure how the IDL would be composed to account for these though, but having them would help complete the IDL translation layer.
The text was updated successfully, but these errors were encountered: