Opened 8 years ago

Last modified 2 years ago

#1957 defect assigned

AMP needs protocol specification document in doc/core/specifications

Reported by: jknight Owned by:
Priority: high Milestone:
Component: core Keywords: documentation
Cc: ed@…, thijs Branch:
Author: Launchpad Bug:

Description (last modified by glyph)

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

Change History (9)

comment:1 Changed 8 years ago by glyph

  • Status changed from new to assigned

comment:2 Changed 8 years ago by glyph

  • Description modified (diff)
  • Summary changed from AMP protocol is undocumented to AMP needs protocol specification document in doc/core/specifications

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.

comment:3 Changed 8 years ago by 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.

comment:4 Changed 8 years ago by edsuom

  • Cc ed@… added

comment:5 Changed 6 years ago by thijs

  • Cc thijs added
  • Keywords documentation added

comment:6 follow-up: Changed 5 years ago by 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

comment:7 in reply to: ↑ 6 Changed 5 years ago by 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.

comment:8 Changed 3 years ago by <automation>

  • Owner glyph deleted

comment:9 Changed 2 years ago by 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.

Note: See TracTickets for help on using tickets.