Inline Docs

[stephenplusplus]

Find a standard library to write docs alongside the code, similar to JSDocs.

[dwsupplee]

This could be a good option :)

https://github.com/phpDocumentor/phpDocumentor2

[dwsupplee]

I spent a little more time doing some research on this one and narrowed it down to two options. If anyone has suggestions for more, please share!

phpDocumentor - The go-to standard over the years for auto generating docs and has gone over a pretty big overhaul in the last few years. There are many maintainers, frequent updates, and they are working to help create a PSR standard for writing docblocks. On the downside, the generated html for the docs is a little rough around the edges.

apigen - Provides a powerful, yet simple interface to create your docs along with a straight forward setup process. The generated html includes a search feature which allows you to skim the docs quickly - this does not appear to be included in phpDocumentor. There seems to be a decent amount of support for the library, but issues can linger for some time. There are some issues that have been open for up to a year regarding PHP 5.6 support.

With all that said, it is my understanding that on the whole the generated html won't be a dealbreaker as we are planning to pass generated json documents to a proprietary framework anyways. I'm leaning towards phpDocumentor still, but any thoughts are appreciated.

[tmatsuo]

JFYI Google App Engine documentation uses phpDocumentor:
https://cloud.google.com/appengine/docs/php/refdocs/

[bshaffer]

++phpdocumentor because of AppEngine

[JustinBeckwith]

PHPDoc works for me

[dwsupplee]

We would like to build the project with inline examples and hash documentation so we can parse the code out to match our docs found here.

I would like to propose the following to fulfill these needs. The hash documentation is based on the PSR-5 PHPDoc standard.

Thoughts? :)

/**
 * Pass in an array of configuration parameters to construct your client.
 *
 * Example:
 * ```
 * $client = new StorageClient([
 *     'keyFilePath' => '/path/to/key/file.json',
 *     'projectId' => 'myAwesomeProject'
 * ]);
 * ```
 * Description for a second example
 * ```
 * $client = new StorageClient([
 *     'keyFile' => $keyFile,
 *     'projectId' => 'myAwesomeProject'
 * ]);
 * ```
 *
 * @param array $config Configuration options {
 *     @type callable $httpHandler Override the default http handler.
 *     @type string $keyFilePath The full path to your service account
 *           credentials .json file retrieved from the Google Developers
 *           Console.
 *     @type array $keyFile The contents of the service account credentials
 *           .json file retrieved from the Google Developers Console.
 *     @type string $projectId The project ID created in the Google
 *           Developers Console.
 * }
 * @return null
 */
public function __construct(array $config = [])
{
}

[bshaffer]

This looks great! Although it may need to be @param string[] $config,
according to their example.

where the psr is concerned, I'm not a fan of the introduction of the term
"hash" into the Php lexicon for what has previously been called array :-/

[dwsupplee]

I'm wondering if that's a typo in the example, according to this you would only use that notation when you expect every element to be a string. The first element is boolean 😖.

[bshaffer]

ok cool, I agree

[dwsupplee]

Closing this out as we're running with phpdocumentor2!