Ticket #222 (closed enhancement: fixed)

Opened 7 years ago

Last modified 3 years ago

Missing common overridable/callable method summaries in docs

Reported by: jknight Owned by: spiv
Priority: highest Milestone:
Component: core Keywords: documentation
Cc: spiv, jknight, hypatia., exarkun Branch:
Author: Launchpad Bug:

Description


Change History

Changed 7 years ago by jknight

There is no section "Things that can happen to your Protocol" and 
"Things you can do from your Protocol" in the Server and Client sections, 
to correspond to the sections (3.6.[45] in ProcessProtocol. I assumed 
when reading the earlier sections that the omission was deliberate, and 
that I should read the API docs to get that info. But, if you're going to 
have it in one section, put it in all of them.

It is somewhat useful to see it (since I haven't even started 
looking at the API docs), so I'd suggest adding it to the other sections 
instead of removing it from the ProcessProtocol section. :)

Changed 7 years ago by spiv

Probably the docs should refer you to the API docs for the
IProtocol interface.

Changed 4 years ago by exarkun

  • keywords documentation, review added; documentation removed
  • owner changed from spiv to jknight
  • component set to core
  • cc hypatia., exarkun added; hypatia removed
  • priority changed from low to highest

Is this the sort of thing you had in mind? If so, should something similar be added to other documents? Which?

Index: clients.xhtml
===================================================================
--- clients.xhtml       (revision 18799)
+++ clients.xhtml       (working copy)
@@ -261,6 +261,26 @@
     self.factory. It can then access attributes of the factory in its logic.
     In the case of LogBot, it opens the file and connects to the channel
     stored in the factory.</p>
-    
+
+    <h2>Further Reading</h2>
+
+    <p>The <code class="API"
+    base="twisted.internet.protocol">Protocol</code> class used throughout
+    this document is a base implementation of <code class="API"
+    base="twisted.internet.interfaces">IProtocol</code> used in most Twisted
+    applications for convenience.  To learn about the complete
+    <code>IProtocol</code> interface, see the API documentation for <code
+    class="API" base ="twisted.internet.interfaces">IProtocol</code>.</p>
+
+    <p>The <code>transport</code> attribute used in some examples in this
+    document provides the <code class="API"
+    base="twisted.internet.interfaces">ITCPTransport</code> interface.  To
+    learn about the complete interface, see the API documentation for <code
+    class="API" base="twisted.internet.interfaces">ITCPTransport</code>.</p>
+
+    <p>Interface classes are a way of specifying what methods and attributes
+    an object has and how they behave.  See the <a href="components.xhtml">
+    Components: Interfaces and Adapters</a> document.</p>
+
   </body>
 </html>

Changed 4 years ago by jerub

  • owner changed from jknight to spiv
  • keywords documentation added; documentation, review removed

In the absence from a response from jknight, I approve the above documentation change. Please apply the patch.

Merry Christmas.

Changed 3 years ago by exarkun

  • status changed from new to closed
  • resolution set to fixed

(In [20652]) Apply protocol documentation patch from #222

Author: exarkun Reviewer: Jerub Fixes #222

Add some text to the end of the client howto explaining some conventions used in the document and where further information can be found.

Note: See TracTickets for help on using tickets.