Create documentation

[mekras]

Document usage of this package.

[dbu]

i wonder whether we should document adapters in the main documentation, or if the README is enough? for HttplugBundle i try to document in the README, but link to it from the documentation. documenting adapters and clients in the general documentation could be an overload of information as its a mix between general information and concrete details for specific implementations.

[sagikazarmark]

Actually I like how @joelwurtz started it in SocketClient: basic details, features could be mentioned in the README, the rest could go into the docs.

Also, we should differentiate between adapters and clients: adapters probably have less to document (as most configuration should go into the underlying client)

[dbu]

i am a bit afraid of flooding the documentation with client specific details. maybe they should use a README and if that is not enough have their own github.io page or readthedocs. this would make it easier to maintain the doc and to structure it.

[sagikazarmark]

Well, i see the point.

I think for separate docs pages we don't have enough content.

I propose document client-specific details in the README then and have a general documentation for clients/adapters which lists the available clients/adapters and gives information about how generally a client should be set up. (Configure undelying client, check README for further client/adapter specific docs)

WDYT?

[dbu]

yes, that sounds like a good plan to me. and the general information really does belong into the common documentation. and of course we can still discuss if it turns out this is not a good solution.

[sagikazarmark]

Sure.

[sagikazarmark]

@mekras I also did check apigen: missing file header does not seem to cause any issues.

[mekras]

@sagikazarmark, so as I said apigen is very tolerant of negligent documentation.

[joelwurtz]

lets move the discussion about file header to php-http/boilerplate#1 ?