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

[exarkun]

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

[thijs]

Where can I find that info?

[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.

[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?

[exarkun]

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

[thijs]

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?

[exarkun]

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.