More examples please

[doapp-ryanp]

The 1.X api docs were awesome in that many of the api's had inline examples. I know ApiGen does not lend its self towards that as easy, but are there any plans for more examples in the 2.x docs themselves?

Would really get people up and going faster and would get a faster adoption rate (which means less time you have to spend supporting your old 1.x code :)

I use ApiGen as well, and I know it supports multi line code in doc with <code> and

/---code
<?php echo "hi";
\---

syntax. They also plan on supporting markdown in future release...

[mtdowling]

One of the ways we're working on addressing this is in the form of end-user documentation. You can see our current progress on the docs branch: https://github.com/aws/aws-sdk-php/tree/docs/docs. Do docs like that help?

[doapp-ryanp]

Looks like a good start. I'm not familiar with RST files - idea here your gonna run them through a compiler of somesort and spit out HTML that will be hosted on github pages or something?

Whatever tool you do use, I think it would be pretty valuable to choose one that is easy for people to contribute to - so people like myself who would be willing to contribute can easily send pull requests.

Also direct contextual (faq.blah#sometopic) linking from the api docs to these docs would be sweet. That way you just PHPdoc the link when your writing the SDK - then you can link from something like http://docs.amazonwebservices.com/aws-sdk-php-2/latest/class-Aws.DynamoDb.DynamoDbClient.html#_scan to http://newurl.com/service-dynamo.html#scanExample

just my 2c.

[mtdowling]

Yeah, we'll generate these docs and host them somewhere. The intent of using reStructuredText and Sphinx is that it will be easy to contribute to them.

We'll see about how to best link between docs. Thanks for your feedback.

[tonydspaniard]

+1 for this.

The new SDK is awesome

[mtdowling]

Our user guide documentation is now hosted at http://docs.aws.amazon.com/aws-sdk-php-2/guide/latest/index.html. This documentation includes various examples for common tasks. We will continue to update these guides and work to improve our API documentation.

Please note that our documentation is open source, and we are happy to accept pull requests that help to improve them: https://github.com/aws/aws-sdk-php/tree/master/docs