Add comments for better code completion (IntelliSense)

[majkel89]

API lacks some code comments that enables IDEs to properly hint code.

Example:

$service = new Google_Service_Analytics(/* ... */);
$accounts = $service->management_accounts->listManagementAccounts([ /* parameters */]);
//                                        ^
//                                        |
//                                        \--- no auto compliteation here
//
$total = $accounts->getTotalResults();
//                 ^
//                 |
//                 \--- no auto compliteation here

Adding south comment would fix the problem.

class Google_Service_Analytics {
    // ...
    /**
     * @var Google_Service_Analytics_ManagementAccounts_Resource
     */
    public $management_accounts;
    // ...
}

Generally code completion:

• improves productivity
• shortens learning time for newcomers
• prevents typo errors that result in fatal errors

I'm willing to update code accordingly.

[SDKiller]

:+1:

[ianbarber]

All those classes are generated unfortunately, so it needs a change to the templates rather than to the classes in the repo. Its a good idea though, and should be fairly straightforward.

[majkel89]

I have already started writing parser to add those comments automatically :8ball:

https://github.com/majkel89/misc/blob/master/GoogleApiPhpClient/GoogleApiAddHints.php

PS: It would be nice to have snippets of documentation as well.

[tyteen4a03]

This would be highly appreciated. Trying to figure out what classes a method can return is rather cumbersome.