This is an archive of the discontinued Mercurial Phabricator instance.

docs: add args/returns docs for some cmdutil, context, and registrar functions
ClosedPublic

Authored by rlevasseur on Nov 16 2017, 6:28 PM.

Details

Summary

When writing my first extension, I found it hard to figure out these functions.
I figured documenting their inputs/outputs would help future authors who
are new to the codebase.

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

rlevasseur created this revision.Nov 16 2017, 6:28 PM
lothiraldan requested changes to this revision.Nov 17 2017, 2:57 AM
lothiraldan added a subscriber: lothiraldan.

Looking good, just need a bunch of fixes. Also, did you tried generating the documentation, I'm not sure how 'parameters' would render in the documentation.

mercurial/context.py
637

I think there is a mistake here, immediate changesets of the current changeset.

638

s/decendents/descendants

mercurial/registrar.py
131–132

Should optionalrepo also be highlighted? `optionalrepo`

135–136

Should inferrepo also be highlighted? `inferrepo`

This revision now requires changes to proceed.Nov 17 2017, 2:57 AM
pulkit added a subscriber: pulkit.Nov 17 2017, 4:05 AM

I see you used the word string at few places, do you mean the Python string? If yes, that won't be true on Python 3 as most of the things are bytes.

rlevasseur marked 4 inline comments as done.Nov 18 2017, 4:10 PM
rlevasseur updated this revision to Diff 3628.
In D1440#23968, @pulkit wrote:

I see you used the word string at few places, do you mean the Python string? If yes, that won't be true on Python 3 as most of the things are bytes.

Ah good to know. I don't have much non-ascii stuff, so didn't notice. Ascii only unicode strings work OK -- if thats intentional/desired/supported, it should probably be doc'd as something like "bytes or ascii-encodable string" so callers don't think they have to use b'foo' or 'foo'.encode() everywhere. I've changed it to "bytes" for now -- let me know if you want "bytes or ascii-encodable string" (or equiv).

Also, did you tried generating the documentation, I'm not sure how 'parameters' would render in the documentation.

I ran make doc, but didn't see it output generated docs based on the code itself. Is there a command I missed? I was just assuming the format is RST for the doc strings, since that seems to be the popular format these days.

durin42 accepted this revision.Nov 20 2017, 6:28 PM
This revision was automatically updated to reflect the committed changes.