Closed mekras closed 8 years ago
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.
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)
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.
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?
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.
Sure.
@mekras I also did check apigen: missing file header does not seem to cause any issues.
@sagikazarmark, so as I said apigen is very tolerant of negligent documentation.
lets move the discussion about file header to https://github.com/php-http/boilerplate/issues/1 ?
Document usage of this package.