Issue #59 new

Missing content in cffi.verify documentation

Nick Coghlan
created an issue

Reviewing the docs based on the python-dev discussion, I noticed most of the parameters to cffi.verify are not documented along with the function - they are only documented with the Verifier constructor signature.

It would be better to document the parameters fully in the convenience function documentation, and then only document the differences in the lower level Verifier docs.

Comments (3)

  1. Armin Rigo

    The arguments are all documented in the early section "The verification step", apart from **kwargs, whose documentation is indeed missing. Is it what you're talking about?

  2. Nick Coghlan reporter

    Yep, we used to suffer from this problem in the stdlib subprocess docs, with too much critical info hidden inside the documentation of the Popen constructor.

    It's better to include that parameter documentation either in a separate section referenced from both places, or else in the convenience API documentation (since that is what most people will be looking up) and then reference that from the lower level constructor documentation.

  3. Armin Rigo

    Ah, possible confusion. The **kwargs are actually documented in detail in "The arguments to ffi.verify() are:", near to the top of the section. However some other arguments are not documented immediately here, but only at the end of the same section. That's some paragraphs later. Could it be what you meant? I don't see any argument whose documentation is delayed until the Verifier constructor signature, which is near the end of the document.

  4. Log in to comment