Ticket #222 (closed enhancement: fixed )

Opened 6 years ago

Last modified 2 years ago

Missing common overridable/callable method summaries in docs

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

Attachments

Change History

  2003-08-22 02:43:24+00:00 changed 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. :)

  2003-08-22 07:53:47+00:00 changed by spiv

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

  2006-12-05 03:13:11+00:00 changed by exarkun

  • cc changed from spiv, jknight, hypatia to spiv, jknight, hypatia., exarkun
  • keywords changed from documentation to documentation, review
  • component set to core
  • owner changed from spiv to jknight
  • 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>

  2006-12-25 13:21:53+00:00 changed by jerub

  • keywords changed from documentation, review to documentation
  • owner changed from jknight to spiv

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

Merry Christmas.

  2007-06-28 19:25:54+00:00 changed 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.