Opened 9 years ago

Last modified 9 years ago

#6483 enhancement new

Remove @see docstrings from IOCPReactor so that full API documentation can be inherited from the appropriate interface

Reported by: arbiter Owned by: arbiter
Priority: normal Milestone:
Component: core Keywords: documentation
Cc: Branch:
Author:

Description

In twisted/internet/iocpreactor/reactor.py follows the same pattern as ticket:6459.

Remove methods that contain only an @see reference will make the API document better.

Attachments (2)

iocpreactor-apidocs-6483.patch (1.7 KB) - added by arbiter 9 years ago.
a possible patch
iocpreactor-apidocs-6483-2.patch (1.7 KB) - added by arbiter 9 years ago.
add L{} docstring to some conditional methods that pydoctor doesn't handle.

Download all attachments as: .zip

Change History (5)

comment:1 Changed 9 years ago by arbiter

Owner: set to arbiter
Status: newassigned

Changed 9 years ago by arbiter

a possible patch

comment:2 Changed 9 years ago by arbiter

Keywords: review added
Owner: arbiter deleted
Status: assignednew

I am not sure if I should remove the @see docstrings in "def listenSSL 0" and "def connectSSL 0" (deleting line 171~173 and 183~185 in the patch I submitted).Because it seems like it only changes from "See Also...." to "Undocumented" after running pydoctor. It seems that it didn't help too much in improving the API document.

comment:3 in reply to:  2 Changed 9 years ago by Richard Wall

Keywords: review removed
Owner: set to arbiter

Replying to arbiter:

I am not sure if I should remove the @see docstrings in "def listenSSL 0" and "def connectSSL 0" (deleting line 171~173 and 183~185 in the patch I submitted).Because it seems like it only changes from "See Also...." to "Undocumented" after running pydoctor. It seems that it didn't help too much in improving the API document.

Thanks arbiter.

Yeah maybe pydoctor doesn't handle inherited interface docstrings for those conditional methods.

You could raise a new pydoctor ticket about that, linking to the IOCP reactor API example.

And meanwhile just leave the @see docstrings in place for those conditional methods.

But make sure that *all* the remaining @see references use L{} markup so that pydoctor creates a hyperlink.

Glad to see that you've managed to get pydoctor set up for testing the API docs locally.

-RichardW.

Changed 9 years ago by arbiter

add L{} docstring to some conditional methods that pydoctor doesn't handle.

Note: See TracTickets for help on using tickets.