AMP needs protocol specification document in doc/core/specifications

[jknight]

The AMP protocol needs protocol-level documentation in the style of doc/core/specifciations/banana.xhtml.

[glyph]

I've updated the description to be a bit clearer. There is already some protocol-level documentation, it's just not explicit enough or in the right place. Anybody with half a brain could figure out how to implement the protocol from it, though.

[jknight]

I agree that it would be pretty clear how to implement the top-level protocol, but it has many other bits in there that's not clearly documented. How do you start tls? What is the format of all the standard Arguments? Etc.

[thijs]

Some IRC comments:

thijs_: so AMP needs a protocol specification document in doc/core/specifications (#1957). does that mean most of amp's huge docstring, if not all, can go? a reference to the spec in the docstring makes more sense, instead of duplicating it in a doc?
[18:03] exarkun: It could link to the information, certainly.  A specification might have a different intended audience from the module docstring, though.
[18:03] exarkun: It might make sense to drop some of the information that is more specification-y, though.
[18:03] thijs_: alright
[18:05] radix: right. the docstring should talk about the API. the spec should talk about the protocol

[glyph]

Replying to thijs:

Some IRC comments: radix: the docstring should talk about the API. the spec should talk about the protocol

+1. I included the protocol information in the docstring mostly to make it easier for the specification writer.

[teratorn]

Whoever does this is free to copy/modify any of the docs on  http://amp-protocol.net - there is a complete protocol breakdown and docs for all the common Argument types.