Ticket #917 (new defect )

Opened 4 years ago

Last modified 3 weeks ago

Not all the examples in the twisted.application.strports docstring are valid

Reported by: exarkun Assigned to: thijs
Type: defect Priority: high
Milestone: Component: core
Keywords: documentation Cc: exarkun, moshez, thijs
Branch: Author:
Launchpad Bug:

Attachments

Change History

  2005-03-11 19:56:54+00:00 changed by exarkun

In particular, the ssl examples which omit private key and certification
information will not work.

  2008-07-09 20:25:46+00:00 changed by thijs

  • cc changed from exarkun, moshez, hypatia to exarkun, moshez, thijs
  • component set to conch
  • branch deleted
  • author deleted

Where can I find that info?

follow-up: ↓ 6   2008-07-09 20:52:04+00:00 changed by exarkun

There's nothing to find. The ssl strport type requires a certificate and assumes "server.pem" if one isn't specified. If the named file isn't found, it fails with an OpenSSL error. The examples that do include filenames don't work either, unless you happen to have certificate/key files around with those names; also most of the examples fail because server.Site requires at least one argument.

  2008-07-09 20:52:31+00:00 changed by exarkun

  • component changed from conch to core

  2008-08-05 21:23:33+00:00 changed by thijs

  • owner changed from moshez to thijs
  • status changed from new to assigned

in reply to: ↑ 3   2008-08-08 07:02:26+00:00 changed by thijs

Replying to exarkun:

There's nothing to find. The ssl strport type requires a certificate and assumes "server.pem" if one isn't specified. If the named file isn't found, it fails with an OpenSSL error. The examples that do include filenames don't work either, unless you happen to have certificate/key files around with those names; also most of the examples fail because server.Site requires at least one argument.

I'd suggest moving the examples from the docstring to the doc section and make them work. Thoughts?

follow-up: ↓ 8   2008-08-10 17:32:29+00:00 changed by exarkun

moving the examples which would be more complicated than one line to get right sounds like a good idea to me.

in reply to: ↑ 7   2008-10-21 09:41:42+00:00 changed by thijs

  • owner changed from thijs to exarkun
  • status changed from assigned to new
  • launchpad_bug deleted

Replying to exarkun:

moving the examples which would be more complicated than one line to get right sounds like a good idea to me.

This reply confuses me, can you clarify?

  2008-10-26 14:39:38+00:00 changed by exarkun

  • owner changed from exarkun to thijs

There's the examples in the docstring which work because they're really simple and there's the examples in the docstring which don't work because they omit required parameters or information. I meant that the ones that don't work should be moved someplace else where the complexity required to make them work won't be overwhelming.

Of course, given that there are modules like twisted.protocols.amp with docstrings as long as your leg, it may also make sense to just make the broken examples work, even if that means making the docstring a lot longer. That at least avoids adding new files and ensures that someone looking at strports will see the strports documentation, rather than overlooking the fact that there's some docs in another file somewhere - a likely possibility, given the poor high-level organization of a lot of our docs.

Note: See TracTickets for help on using tickets.