Params and Returns missing 'comment' field

[chuyskywalker]

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:

/**
 * Manage Page Content on site
 */
class Content {

    /**
     * Add a new page to the system.
     *
     * createdTime, updatedTime, version, and id are automatically set upon creation.
     *
     * @param string $authorId
     * @param string $title
     * @param string $body
     * @param string[] $tags
     * @param PageCategory $category
     *
     * @return string The generated page id
     */
    public function addPage($authorId, $title, $body, array $tags, PageCategory $category) {}

}

Corresponding IDL:

// Manage Page Content on site
interface Content {

    // Add a new page to the system.
    //
    // createdTime, updatedTime, version, and id are automatically set upon creation.
    addPage(authorId string, title string, body string, tags []string, category PageCategory) string

}

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.

[chuyskywalker]

Some thoughts:

interface Content {
    // Add a new page to the system.
    addPage(authorId string "Comment", title string, body string "Comment", tags []string "Comment", category PageCategory) string  "Comment"
}

Perhaps? Where "Comment" is optional. Would start to look kind sill though with long comments:

interface Content {
    // Add a new page to the system.
    addPage(authorId string "The author ID", title string "The title of the new page", body string "The body content of the new page, HTML/Markup recommended", tags []string "An array of strings representing tags for the page", category PageCategory) string  "An automatically generated ID, usually based on the title"
}

So, line breaking?

interface Content {
    // Add a new page to the system.
    addPage(
        authorId string "The author ID", 
        title string "The title of the new page", 
        body string "The body content of the new page, HTML/Markup recommended",
        tags []string "An array of strings representing tags for the page", 
        category PageCategory
    ) string  "An automatically generated ID, usually based on the title"
}

At which point, perhaps "real" comments make more sense

interface Content {
    // Add a new page to the system.
    addPage(
        authorId string,      // The author ID
        title    string,      // The title of the new page
        body     string,      // The body content of the new page, HTML/Markup recommended
        tags     []string,    // An array of strings representing tags for the page
        category PageCategory
    ) string                  // An automatically generated ID, usually based on the title
}

[coopernurse]

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