Opened 5 years ago

Closed 4 years ago

#6328 enhancement closed fixed (fixed)

twisted.names.client lookup functions duplicate or reference the documentation of `IResolver`

Reported by: Richard Wall Owned by: Richard Wall
Priority: normal Milestone:
Component: names Keywords: documentation
Cc: Branch: branches/moduleprovides-iresolver-6328-2
branch-diff, diff-cov, branch-cov, buildbot
Author: rwall

Description (last modified by Tom Prince)

In order to document the free functions in twistd.names.client implement most of the interface of IResolver, so the documentation should match them. #4685 handles this by just having @see` annotations. It would be better if we could include the documentation automatically.

See:

"""

In #4685?replyto=16#comment:12 we have a series of module global functions which provide the twisted.internet.interfaces.IResolver interface.

We currently insert @see: L{twisted.internet.interfaces.IResolver.lookupAddress} so that we see links to the interface docs in the pydoctor api docs.

It would be nicer if pydoctor could find and insert the interface documentation - just like it does when it encounters an @implementer decorator.

See:

"""

Change History (10)

comment:1 Changed 5 years ago by Tom Prince

Keywords: documentation added

comment:2 Changed 5 years ago by Tom Prince

Owner: set to Tom Prince

comment:3 Changed 5 years ago by Tom Prince

Description: modified (diff)
Summary: twisted.names.client lookup functions api documentation should be inserted via zope.interface.moduleProvidestwisted.names.client lookup functions duplicate or reference the documntation of `IResolver`

comment:4 Changed 5 years ago by Richard Wall

Branch: branches/moduleprovides-iresolver-6328
Owner: changed from Tom Prince to Richard Wall
Status: newassigned

comment:5 Changed 5 years ago by Richard Wall

I submitted a patch to pydoctor which allows it to interpret moduleProvides.

I tested it on this branch.

comment:6 Changed 4 years ago by Richard Wall

Author: rwall
Branch: branches/moduleprovides-iresolver-6328branches/moduleprovides-iresolver-6328-2

(In [38291]) Branching to 'moduleprovides-iresolver-6328-2'

comment:7 Changed 4 years ago by Richard Wall

Keywords: review added
Owner: Richard Wall deleted
Status: assignednew

Ready for review in log:branches/moduleprovides-iresolver-6328-2

mwhudson merged my pydoctor patch some time ago:

tomprince updated to the trunk version of pydoctor in the buildbot documentation builder yesterday to fix #5681.

So the API documentation should now contain full docs for the client.lookup functions.

Summary of branch changes.

  1. I've tidied up and added some missing docstrings to IResolver.getHostByName
  2. Added a new test to verify that the t.n.client module object "provides" the IResolverInterface.
  3. Added client.query function to satisfy the IResolverInterface.
  4. Removed docstrings from the client.lookup functions

I wanted to remove the docstring for twisted.names.client.getHostByName, but that version of the function contains an "effort" argument which is not in IResolverSimple.getHostByName. I've raised #6496 to suggest removing the effort argument.

-RichardW.

comment:8 Changed 4 years ago by therve

Summary: twisted.names.client lookup functions duplicate or reference the documntation of `IResolver`twisted.names.client lookup functions duplicate or reference the documentation of `IResolver`

comment:9 Changed 4 years ago by Tom Prince

Keywords: review removed
Owner: set to Richard Wall

This looks good, thanks. The only issue is that test_querys docstring doesn't follow the coding standard (and the docstring that it references could be improved).

Please merge after improving the docstring for test_query.

comment:10 Changed 4 years ago by Richard Wall

Resolution: fixed
Status: newclosed

(In [38951]) Merge moduleprovides-iresolver-6328-2

Author: rwall Reviewer: tom.prince Fixes: #6328

Use zope.interface.moduleProvides to allow pydoctor to properly document the twisted.names.client.lookup* functions.

Note: See TracTickets for help on using tickets.