From 8e40dbd314057b5594a18139c777fe1081079f39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=2E=20David=20Ib=C3=A1=C3=B1ez?= Date: Sat, 9 Feb 2013 23:46:37 +0100 Subject: [PATCH] Make doc strings look fine from the interpreter Basically add a new-line character since "help(...)" does not wrap lines automatically. --- docs/install.rst | 2 +- src/config.c | 35 +++++++++------ src/diff.c | 6 ++- src/index.c | 37 ++++++++++------ src/object.c | 2 +- src/pygit2.c | 6 ++- src/reference.c | 15 ++++--- src/repository.c | 107 +++++++++++++++++++++++++++------------------- src/signature.c | 2 +- src/tree.c | 26 ++++++----- src/treebuilder.c | 14 +++--- src/walker.c | 12 ++++-- 12 files changed, 159 insertions(+), 105 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 8728b93..8bf6bcd 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -53,7 +53,7 @@ instructions in the libgit2 ``README.md``):: $ cd libgit2/build $ cmake .. $ cmake --build . - $ sudo cmake --build . --target install + $ sudo cmake --build . --target install $ cd ../.. Now, download and install pygit2. You will probably have to set the diff --git a/src/config.c b/src/config.c index 847f9f8..687acbd 100644 --- a/src/config.c +++ b/src/config.c @@ -100,7 +100,8 @@ Config_open(char *c_path) { PyDoc_STRVAR(Config_get_global_config__doc__, - "get_global_config() -> Config\n\n" + "get_global_config() -> Config\n" + "\n" "Return an object representing the global configuration file."); PyObject * @@ -123,7 +124,8 @@ Config_get_global_config(void) PyDoc_STRVAR(Config_get_system_config__doc__, - "get_system_config() -> Config\n\n" + "get_system_config() -> Config\n" + "\n" "Return an object representing the system configuration file."); PyObject * @@ -266,11 +268,13 @@ Config_foreach_callback_wrapper(const git_config_entry *entry, void *c_payload) PyDoc_STRVAR(Config_foreach__doc__, - "foreach(callback[, payload]) -> int\n\n" - "Perform an operation on each config variable.\n\n" - "The callback must be of type Callable and receives the normalized name " - "and value of each variable in the config backend, and an optional payload " - "passed to this method. As soon as one of the callbacks returns an integer " + "foreach(callback[, payload]) -> int\n" + "\n" + "Perform an operation on each config variable.\n" + "\n" + "The callback must be of type Callable and receives the normalized name\n" + "and value of each variable in the config backend, and an optional payload\n" + "passed to this method. As soon as one of the callbacks returns an integer\n" "other than 0, this function returns that value."); PyObject * @@ -297,7 +301,8 @@ Config_foreach(Config *self, PyObject *args) PyDoc_STRVAR(Config_add_file__doc__, - "add_file(path, level=0, force=0)\n\n" + "add_file(path, level=0, force=0)\n" + "\n" "Add a config file instance to an existing config."); PyObject * @@ -324,10 +329,11 @@ Config_add_file(Config *self, PyObject *args, PyObject *kwds) PyDoc_STRVAR(Config_get_multivar__doc__, - "get_multivar(name[, regex]) -> [str, ...]\n\n" - "Get each value of a multivar ''name'' as a list. The optional ''regex'' " - "parameter is expected to be a regular expression to filter the variables " - " we're interested in."); + "get_multivar(name[, regex]) -> [str, ...]\n" + "\n" + "Get each value of a multivar ''name'' as a list. The optional ''regex''\n" + "parameter is expected to be a regular expression to filter the variables\n" + "we're interested in."); int Config_get_multivar_fn_wrapper(const git_config_entry *value, void *data) @@ -370,8 +376,9 @@ Config_get_multivar(Config *self, PyObject *args) PyDoc_STRVAR(Config_set_multivar__doc__, - "set_multivar(name, regex, value)\n\n" - "Set a multivar ''name'' to ''value''. ''regexp'' is a regular expression " + "set_multivar(name, regex, value)\n" + "\n" + "Set a multivar ''name'' to ''value''. ''regexp'' is a regular expression\n" "to indicate which values to replace"); PyObject * diff --git a/src/diff.c b/src/diff.c index 94eb6a9..581388e 100644 --- a/src/diff.c +++ b/src/diff.c @@ -347,7 +347,8 @@ PyTypeObject HunkType = { PyDoc_STRVAR(Diff_merge__doc__, - "merge(diff)\n\n" + "merge(diff)\n" + "\n" "Merge one diff into another."); PyObject * @@ -372,7 +373,8 @@ Diff_merge(Diff *self, PyObject *args) PyDoc_STRVAR(Diff_find_similar__doc__, - "find_similar([flags])\n\n" + "find_similar([flags])\n" + "\n" "Find renamed files in diff."); PyObject * diff --git a/src/index.c b/src/index.c index 2c6793b..1a6d3ac 100644 --- a/src/index.c +++ b/src/index.c @@ -80,7 +80,8 @@ Index_traverse(Index *self, visitproc visit, void *arg) PyDoc_STRVAR(Index_add__doc__, - "add(path)\n\n" + "add(path)\n" + "\n" "Add or update an index entry from a file in disk."); PyObject * @@ -101,7 +102,8 @@ Index_add(Index *self, PyObject *args) PyDoc_STRVAR(Index_clear__doc__, - "clear()\n\n" + "clear()\n" + "\n" "Clear the contents (all the entries) of an index object."); PyObject * @@ -113,9 +115,10 @@ Index_clear(Index *self) PyDoc_STRVAR(Index_diff__doc__, - "diff([tree]) -> Diff\n\n" - "Return a :py:class:`~pygit2.Diff` object with the differences between the " - "index and the working copy. If a :py:class:`~pygit2.Tree` object is " + "diff([tree]) -> Diff\n" + "\n" + "Return a :py:class:`~pygit2.Diff` object with the differences between the\n" + "index and the working copy. If a :py:class:`~pygit2.Tree` object is\n" "passed, return the diferences between the index and the given tree."); PyObject * @@ -163,8 +166,9 @@ Index_diff(Index *self, PyObject *args) PyDoc_STRVAR(Index__find__doc__, - "_find(path) -> integer\n\n" - "Find the first index of any entries which point to given path in the " + "_find(path) -> integer\n" + "\n" + "Find the first index of any entries which point to given path in the\n" "index file."); PyObject * @@ -187,8 +191,9 @@ Index__find(Index *self, PyObject *py_path) PyDoc_STRVAR(Index_read__doc__, - "read()\n\n" - "Update the contents of an existing index object in memory by reading from " + "read()\n" + "\n" + "Update the contents of an existing index object in memory by reading from\n" "the hard disk."); PyObject * @@ -205,8 +210,9 @@ Index_read(Index *self) PyDoc_STRVAR(Index_write__doc__, - "write()\n\n" - "Write an existing index object from memory back to disk using an atomic " + "write()\n" + "\n" + "Write an existing index object from memory back to disk using an atomic\n" "file lock."); PyObject * @@ -334,7 +340,8 @@ Index_getitem(Index *self, PyObject *value) PyDoc_STRVAR(Index_remove__doc__, - "remove(path)\n\n" + "remove(path)\n" + "\n" "Removes an entry from index."); PyObject * @@ -372,7 +379,8 @@ Index_setitem(Index *self, PyObject *key, PyObject *value) PyDoc_STRVAR(Index_read_tree__doc__, - "read_tree(tree)\n\n" + "read_tree(tree)\n" + "\n" "Update the index file from the tree identified by the given oid."); PyObject * @@ -401,7 +409,8 @@ Index_read_tree(Index *self, PyObject *value) PyDoc_STRVAR(Index_write_tree__doc__, - "write_tree() -> str\n\n" + "write_tree() -> str\n" + "\n" "Create a tree object from the index file, return its oid."); PyObject * diff --git a/src/object.c b/src/object.c index 1b64be5..48667e5 100644 --- a/src/object.c +++ b/src/object.c @@ -80,7 +80,7 @@ Object_hex__get__(Object *self) PyDoc_STRVAR(Object_type__doc__, - "One of the GIT_OBJ_COMMIT, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_TAG " + "One of the GIT_OBJ_COMMIT, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_TAG\n" "constants."); PyObject * diff --git a/src/pygit2.c b/src/pygit2.c index fdadb52..15d1a3f 100644 --- a/src/pygit2.c +++ b/src/pygit2.c @@ -60,7 +60,8 @@ extern PyTypeObject SignatureType; PyDoc_STRVAR(init_repository__doc__, - "init_repository(path, bare) -> Repository\n\n" + "init_repository(path, bare) -> Repository\n" + "\n" "Creates a new Git repository in the given path."); PyObject * @@ -93,7 +94,8 @@ init_repository(PyObject *self, PyObject *args) PyDoc_STRVAR(discover_repository__doc__, - "discover_repository(path[, across_fs[, ceiling_dirs]]) -> str\n\n" + "discover_repository(path[, across_fs[, ceiling_dirs]]) -> str\n" + "\n" "Look for a git repository and return its path."); PyObject * diff --git a/src/reference.c b/src/reference.c index cccbfdb..7695540 100644 --- a/src/reference.c +++ b/src/reference.c @@ -131,7 +131,8 @@ Reference_dealloc(Reference *self) PyDoc_STRVAR(Reference_delete__doc__, - "delete()\n\n" + "delete()\n" + "\n" "Delete this reference. It will no longer be valid!"); PyObject * @@ -152,7 +153,8 @@ Reference_delete(Reference *self, PyObject *args) PyDoc_STRVAR(Reference_rename__doc__, - "rename(new_name)\n\n" + "rename(new_name)\n" + "\n" "Rename the reference."); PyObject * @@ -179,7 +181,8 @@ Reference_rename(Reference *self, PyObject *py_name) PyDoc_STRVAR(Reference_reload__doc__, - "reload()\n\n" + "reload()\n" + "\n" "Reload the reference from the file-system."); PyObject * @@ -200,7 +203,8 @@ Reference_reload(Reference *self) PyDoc_STRVAR(Reference_resolve__doc__, - "resolve() -> Reference\n\n" + "resolve() -> Reference\n" + "\n" "Resolve a symbolic reference and return a direct reference."); PyObject * @@ -377,7 +381,8 @@ Reference_type__get__(Reference *self) PyDoc_STRVAR(Reference_log__doc__, - "log() -> RefLogIter\n\n" + "log() -> RefLogIter\n" + "\n" "Retrieves the current reference log."); PyObject * diff --git a/src/repository.c b/src/repository.c index 79c704b..f8a5708 100644 --- a/src/repository.c +++ b/src/repository.c @@ -208,12 +208,12 @@ Repository_head__get__(Repository *self) err = git_repository_head(&head, self->repo); if(err < 0) { - if(err == GIT_ENOTFOUND) - PyErr_SetString(GitError, "head reference does not exist"); - else - Error_set(err); + if(err == GIT_ENOTFOUND) + PyErr_SetString(GitError, "head reference does not exist"); + else + Error_set(err); - return NULL; + return NULL; } oid = git_reference_target(head); @@ -224,7 +224,7 @@ Repository_head__get__(Repository *self) PyDoc_STRVAR(Repository_head_is_detached__doc__, - "A repository's HEAD is detached when it points directly to a commit " + "A repository's HEAD is detached when it points directly to a commit\n" "instead of a branch."); PyObject * @@ -238,7 +238,7 @@ Repository_head_is_detached__get__(Repository *self) PyDoc_STRVAR(Repository_head_is_orphaned__doc__, - "An orphan branch is one named from HEAD but which doesn't exist in the " + "An orphan branch is one named from HEAD but which doesn't exist in the\n" "refs namespace, because it doesn't have any commit to point to."); PyObject * @@ -292,9 +292,10 @@ Repository_getitem(Repository *self, PyObject *value) PyDoc_STRVAR(Repository_revparse_single__doc__, - "revparse_single(revision) -> Object\n\n" - "Find an object, as specified by a revision string. See " - "`man gitrevisions`, or the documentation for `git rev-parse` for " + "revparse_single(revision) -> Object\n" + "\n" + "Find an object, as specified by a revision string. See\n" + "`man gitrevisions`, or the documentation for `git rev-parse` for\n" "information on the syntax accepted."); PyObject * @@ -348,7 +349,8 @@ Repository_read_raw(git_repository *repo, const git_oid *oid, size_t len) PyDoc_STRVAR(Repository_read__doc__, - "read(oid) -> type, data, size\n\n" + "read(oid) -> type, data, size\n" + "\n" "Read raw object data from the repository."); PyObject * @@ -379,10 +381,11 @@ Repository_read(Repository *self, PyObject *py_hex) PyDoc_STRVAR(Repository_write__doc__, - "write(type, data) -> oid\n\n" - "Write raw object data into the repository. First arg is the object " - "type, the second one a buffer with data. Return the object id (sha) " - "of the created object."); + "write(type, data) -> oid\n" + "\n" + "Write raw object data into the repository. First arg is the object type,\n" + "the second one a buffer with data. Return the object id (sha) of of the\n" + "created object."); PyObject * Repository_write(Repository *self, PyObject *args) @@ -464,8 +467,8 @@ Repository_path__get__(Repository *self, void *closure) PyDoc_STRVAR(Repository_workdir__doc__, - "The normalized path to the working directory of the repository. " - "If the repository is bare, None will be returned."); + "The normalized path to the working directory of the repository. If the\n" + "repository is bare, None will be returned."); PyObject * Repository_workdir__get__(Repository *self, void *closure) @@ -481,9 +484,10 @@ Repository_workdir__get__(Repository *self, void *closure) PyDoc_STRVAR(Repository_config__doc__, - "Get the configuration file for this repository.\n\n" - "If a configuration file has not been set, the default config set for the " - "repository will be returned, including global and system configurations " + "Get the configuration file for this repository.\n" + "\n" + "If a configuration file has not been set, the default config set for the\n" + "repository will be returned, including global and system configurations\n" "(if they are available)."); PyObject * @@ -519,7 +523,8 @@ Repository_config__get__(Repository *self, void *closure) PyDoc_STRVAR(Repository_walk__doc__, - "walk(oid, sort_mode) -> iterator\n\n" + "walk(oid, sort_mode) -> iterator\n" + "\n" "Generator that traverses the history starting from the given commit."); PyObject * @@ -571,7 +576,8 @@ Repository_walk(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_blob__doc__, - "create_blob(data) -> bytes\n\n" + "create_blob(data) -> bytes\n" + "\n" "Create a new blob from memory."); PyObject * @@ -594,7 +600,8 @@ Repository_create_blob(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_blob_fromfile__doc__, - "create_blob_fromfile(path) -> bytes\n\n" + "create_blob_fromfile(path) -> bytes\n" + "\n" "Create a new blob from file."); PyObject * @@ -616,8 +623,8 @@ Repository_create_blob_fromfile(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_create_commit__doc__, - "create_commit(reference, author, committer, message, tree, parents" - "[, encoding]) -> bytes\n\n" + "create_commit(reference, author, committer, message, tree, parents[, encoding]) -> bytes\n" + "\n" "Create a new commit object, return its SHA."); PyObject * @@ -699,7 +706,8 @@ out: PyDoc_STRVAR(Repository_create_tag__doc__, - "create_tag(name, oid, type, tagger, message) -> bytes\n\n" + "create_tag(name, oid, type, tagger, message) -> bytes\n" + "\n" "Create a new tag object, return its SHA."); PyObject * @@ -736,7 +744,8 @@ Repository_create_tag(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_listall_references__doc__, - "listall_references([flags]) -> (str, ...)\n\n" + "listall_references([flags]) -> (str, ...)\n" + "\n" "Return a tuple with all the references in the repository."); PyObject * @@ -779,7 +788,8 @@ out: PyDoc_STRVAR(Repository_lookup_reference__doc__, - "lookup_reference(name) -> Reference\n\n" + "lookup_reference(name) -> Reference\n" + "\n" "Lookup a reference by its name in a repository."); PyObject * @@ -809,23 +819,25 @@ Repository_lookup_reference(Repository *self, PyObject *py_name) PyDoc_STRVAR(Repository_create_reference__doc__, "create_reference(name, source, force=False, symbolic=False) -> Reference\n" "\n" - "Create a new reference \"name\" which points to a object or another " - "reference\n" + "Create a new reference \"name\" which points to a object or another\n" + "reference.\n" "\n" "Keyword arguments:\n" "\n" - "force -- if True references will be overridden, otherwise (the default)" - " an exception is raised.\n" + "force\n" + " If True references will be overridden, otherwise (the default) an\n" + " exception is raised.\n" "\n" - "symbolic -- if True a symbolic reference will be created, then source has" - " to be a valid existing reference name; if False (the default)" - " a normal reference will be created, then source must has to be" - " a valid SHA hash.\n" + "symbolic\n" + " If True a symbolic reference will be created, then source has to be a\n" + " valid existing reference name; if False (the default) a normal\n" + " reference will be created, then source must has to be a valid SHA\n" + " hash.\n" "\n" "Examples::\n" "\n" " repo.create_reference('refs/heads/foo', repo.head.hex)\n" - " repo.create_reference('refs/tags/foo', 'refs/heads/master', symbolic=True)\n"); + " repo.create_reference('refs/tags/foo', 'refs/heads/master', symbolic=True)"); PyObject * Repository_create_reference(Repository *self, PyObject *args, PyObject *kw) @@ -870,8 +882,9 @@ Repository_create_reference(Repository *self, PyObject *args, PyObject *kw) PyDoc_STRVAR(Repository_packall_references__doc__, - "packall_references()\n\n" - "Pack all the loose references in the repository."); + "packall_references()\n" + "\n" + "Pack all the loose references in the repository."); PyObject * Repository_packall_references(Repository *self, PyObject *args) @@ -887,8 +900,9 @@ Repository_packall_references(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_status__doc__, - "status() -> {str: int}\n\n" - "Reads the status of the repository and returns a dictionary with file " + "status() -> {str: int}\n" + "\n" + "Reads the status of the repository and returns a dictionary with file\n" "paths as keys and status flags as values. See pygit2.GIT_STATUS_*."); int @@ -917,7 +931,8 @@ Repository_status(Repository *self, PyObject *args) PyDoc_STRVAR(Repository_status_file__doc__, - "status_file(path) -> int\n\n" + "status_file(path) -> int\n" + "\n" "Returns the status of the given file path."); PyObject * @@ -942,7 +957,8 @@ Repository_status_file(Repository *self, PyObject *value) PyDoc_STRVAR(Repository_TreeBuilder__doc__, - "TreeBuilder([tree]) -> TreeBuilder\n\n" + "TreeBuilder([tree]) -> TreeBuilder\n" + "\n" "Create a TreeBuilder object for this repository."); PyObject * @@ -1048,8 +1064,9 @@ PyMappingMethods Repository_as_mapping = { PyDoc_STRVAR(Repository__doc__, - "Repository(path) -> Repository\n\n" - "Git repository."); + "Repository(path) -> Repository\n" + "\n" + "Git repository."); PyTypeObject RepositoryType = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/src/signature.c b/src/signature.c index db25968..88f2f87 100644 --- a/src/signature.c +++ b/src/signature.c @@ -151,7 +151,7 @@ Signature_time__get__(Signature *self) } -PyDoc_STRVAR(Signature_offset__doc__, "Offset from UTC in minutes"); +PyDoc_STRVAR(Signature_offset__doc__, "Offset from UTC in minutes."); PyObject * Signature_offset__get__(Signature *self) diff --git a/src/tree.c b/src/tree.c index feb9a1a..6514ecd 100644 --- a/src/tree.c +++ b/src/tree.c @@ -88,7 +88,8 @@ TreeEntry_hex__get__(TreeEntry *self) PyDoc_STRVAR(TreeEntry_to_object__doc__, - "to_object() -> Object\n\n" + "to_object() -> Object\n" + "\n" "Look up the corresponding object in the repo."); PyObject * @@ -287,16 +288,19 @@ Tree_getitem(Tree *self, PyObject *value) PyDoc_STRVAR(Tree_diff__doc__, - "diff([obj, flags]) -> Diff\n\n" - "Get changes between current tree instance with another tree, an index " - "or the working dir.\n" - "\n" - "Arguments:\n" - "\n" - "obj -- if not given compare diff against working dir. " - " Possible valid arguments are instances of Tree or Index.\n" - "\n" - "flags -- "); + "diff([obj, flags]) -> Diff\n" + "\n" + "Get changes between current tree instance with another tree, an index or\n" + "the working dir.\n" + "\n" + "Arguments:\n" + "\n" + "obj\n" + " If not given compare diff against working dir. Possible valid\n" + " arguments are instances of Tree or Index.\n" + "\n" + "flags\n" + " TODO"); PyObject * Tree_diff(Tree *self, PyObject *args) diff --git a/src/treebuilder.c b/src/treebuilder.c index c1acb9a..7c45f42 100644 --- a/src/treebuilder.c +++ b/src/treebuilder.c @@ -44,7 +44,8 @@ TreeBuilder_dealloc(TreeBuilder *self) PyDoc_STRVAR(TreeBuilder_insert__doc__, - "insert(name, oid, attr)\n\n" + "insert(name, oid, attr)\n" + "\n" "Insert or replace an entry in the treebuilder."); PyObject * @@ -75,7 +76,8 @@ TreeBuilder_insert(TreeBuilder *self, PyObject *args) PyDoc_STRVAR(TreeBuilder_write__doc__, - "write() -> bytes\n\n" + "write() -> bytes\n" + "\n" "Write the tree to the given repository."); PyObject * @@ -93,7 +95,8 @@ TreeBuilder_write(TreeBuilder *self) PyDoc_STRVAR(TreeBuilder_remove__doc__, - "remove(name)\n\n" + "remove(name)\n" + "\n" "Remove an entry from the builder."); PyObject * @@ -115,7 +118,8 @@ TreeBuilder_remove(TreeBuilder *self, PyObject *py_filename) PyDoc_STRVAR(TreeBuilder_clear__doc__, - "clear()\n\n" + "clear()\n" + "\n" "Clear all the entries in the builder."); PyObject * @@ -134,7 +138,7 @@ PyMethodDef TreeBuilder_methods[] = { }; -PyDoc_STRVAR(TreeBuilder__doc__, "TreeBuilder objects"); +PyDoc_STRVAR(TreeBuilder__doc__, "TreeBuilder objects."); PyTypeObject TreeBuilderType = { PyVarObject_HEAD_INIT(NULL, 0) diff --git a/src/walker.c b/src/walker.c index f7f0b14..d1b128c 100644 --- a/src/walker.c +++ b/src/walker.c @@ -45,7 +45,8 @@ Walker_dealloc(Walker *self) PyDoc_STRVAR(Walker_hide__doc__, - "hide(oid)\n\n" + "hide(oid)\n" + "\n" "Mark a commit (and its ancestors) uninteresting for the output."); PyObject * @@ -67,7 +68,8 @@ Walker_hide(Walker *self, PyObject *py_hex) PyDoc_STRVAR(Walker_push__doc__, - "push(oid)\n\n" + "push(oid)\n" + "\n" "Mark a commit to start traversal from."); PyObject * @@ -89,7 +91,8 @@ Walker_push(Walker *self, PyObject *py_hex) PyDoc_STRVAR(Walker_sort__doc__, - "sort(mode)\n\n" + "sort(mode)\n" + "\n" "Change the sorting mode (this resets the walker)."); PyObject * @@ -108,7 +111,8 @@ Walker_sort(Walker *self, PyObject *py_sort_mode) PyDoc_STRVAR(Walker_reset__doc__, - "reset()\n\n" + "reset()\n" + "\n" "Reset the walking machinery for reuse."); PyObject *