Ticket #1957 defect assigned

Opened 8 years ago

Last modified 22 months ago

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) (diff)

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

Change History

1

  Changed 8 years ago by glyph

  • status changed from new to assigned

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.

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.

4

  Changed 8 years ago by edsuom

  • cc ed@… added

5

  Changed 5 years ago by thijs

  • cc thijs added
  • keywords documentation added

6

follow-up: ↓ 7   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

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.

8

  Changed 3 years ago by <automation>

  • owner glyph deleted

9

  Changed 22 months 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.