More api doc improvements.

dulwich/contrib/diffstat.py

@@ -56,15 +56,11 @@ _GIT_UNCHANGED_START = b" "
 
 
 def _parse_patch(lines):
-    """An internal routine to parse a git style diff or patch to generate
-       diff stats
+    """Parse a git style diff or patch to generate diff stats.
+
     Args:
-      lines: list of byte strings "lines" from the diff to be parsed
-    Returns: A tuple (names, nametypes, counts) of three lists:
-             names = list of repo relative file paths
-             nametypes - list of booolean values indicating if file
-                         is binary (True means binary file)
-             counts = list of tuples of (added, deleted) counts for that file
+      lines: list of byte string lines from the diff to be parsed
+    Returns: A tuple (names, is_binary, counts) of three lists
     """
     names = []
     nametypes = []

dulwich/index.py

@@ -579,7 +579,7 @@ def build_file_from_blob(
     """Build a file or symlink on disk based on a Git object.
 
     Args:
-      obj: The git object
+      blob: The git object
       mode: File mode
       target_path: Path to write to
       honor_filemode: An optional flag to honor core.filemode setting in
@@ -718,7 +718,7 @@ def blob_from_path_and_mode(fs_path, mode, tree_encoding="utf-8"):
 
     Args:
       fs_path: Full file system path to file
-      st: A stat object
+      mode: File mode
     Returns: A `Blob` object
     """
     assert isinstance(fs_path, bytes)
@@ -916,7 +916,7 @@ def iter_fresh_entries(
     Args:
       paths: Paths to iterate over
       root_path: Root path to access from
-      store: Optional store to save new blobs in
+      object_store: Optional store to save new blobs in
     Returns: Iterator over path, index_entry
     """
     for path in paths:

dulwich/line_ending.py

@@ -112,7 +112,7 @@ attribute defined in ``.gitattributes``; it takes three possible values:
       line-endings converted to LF.
     - ``false`` (default): No normalization is done.
 
-`core.eol` is the top-level configuration to define the line-ending to use
+``core.eol`` is the top-level configuration to define the line-ending to use
 when applying the read_filer. It takes three possible values:
 
     - ``lf``: When normalization is done, force line-endings to be ``LF`` in the

dulwich/object_store.py

@@ -158,7 +158,7 @@ class BaseObjectStore(object):
         """Add pack data to this object store.
 
         Args:
-          num_items: Number of items to add
+          count: Number of items to add
           pack_data: Iterator over pack data tuples
         """
         if count == 0:

dulwich/objects.py

@@ -222,7 +222,7 @@ def check_time(time_seconds):
     This will raise an exception if the time is not valid.
 
     Args:
-      time_info: author/committer/tagger info
+      time_seconds: time in seconds
 
     """
     # Prevent overflow error

dulwich/objectspec.py

@@ -94,7 +94,7 @@ def parse_reftuple(lh_container, rh_container, refspec, force=False):
 
     Args:
       lh_container: A RefsContainer object
-      hh_container: A RefsContainer object
+      rh_container: A RefsContainer object
       refspec: A string
     Returns: A tuple with left and right ref
     Raises:
@@ -132,7 +132,7 @@ def parse_reftuples(
 
     Args:
       lh_container: A RefsContainer object
-      hh_container: A RefsContainer object
+      rh_container: A RefsContainer object
       refspecs: A list of refspecs or a string
       force: Force overwriting for all reftuples
     Returns: A list of refs
@@ -211,7 +211,7 @@ def parse_commit(repo, committish):
 
     Args:
       repo: A` Repo` object
-      commitish: A string referring to a single commit.
+      committish: A string referring to a single commit.
     Returns: A Commit object
     Raises:
       KeyError: When the reference commits can not be found

dulwich/pack.py

@@ -274,7 +274,7 @@ def load_pack_index(path):
     """Load an index file by path.
 
     Args:
-      filename: Path to the index file
+      path: Path to the index file
     Returns: A PackIndex loaded from the given path
     """
     with GitFile(path, "rb") as f:
@@ -1599,9 +1599,8 @@ def write_pack(
 
     Args:
       filename: Path to the new pack file (without .pack extension)
-      objects: Iterable of (object, path) tuples to write.
-        Should provide __len__
-      window_size: Delta window size
+      objects: (object, path) tuple iterable to write. Should provide __len__
+      delta_window_size: Delta window size
       deltify: Whether to deltify pack objects
       compression_level: the zlib compression level
     Returns: Tuple with checksum of pack file and index file
@@ -1688,10 +1687,10 @@ def write_pack_objects(
 
     Args:
       f: File to write to
-      objects: Iterable of (object, path) tuples to write.
-        Should provide __len__
-      window_size: Sliding window size for searching for deltas;
-                        Set to None for default window size.
+      objects: Iterable of (object, path) tuples to write. Should provide
+         __len__
+      delta_window_size: Sliding window size for searching for deltas;
+                         Set to None for default window size.
       deltify: Whether to deltify objects
       compression_level: the zlib compression level to use
     Returns: Dict mapping id -> (offset, crc32 checksum), pack checksum

dulwich/porcelain.py

@@ -508,7 +508,7 @@ def _is_subdir(subdir, parentdir):
 def clean(repo=".", target_dir=None):
     """Remove any untracked files from the target directory recursively
 
-    Equivalent to running `git clean -fd` in target_dir.
+    Equivalent to running ``git clean -fd`` in target_dir.
 
     Args:
       repo: Repository where the files may be tracked
@@ -1107,7 +1107,7 @@ def pull(
     Args:
       repo: Path to repository
       remote_location: Location of the remote
-      refspec: refspecs to fetch
+      refspecs: refspecs to fetch
       outstream: A stream file to write to output
       errstream: A stream file to write to errors
     """
@@ -1159,7 +1159,7 @@ def status(repo=".", ignored=False):
 
     Args:
       repo: Path to repository or repository object
-      ignored: Whether to include ignored files in `untracked`
+      ignored: Whether to include ignored files in untracked
     Returns: GitStatus tuple,
         staged -  dict with lists of staged paths (diff index/HEAD)
         unstaged -  list of unstaged paths (diff index/working-tree)
@@ -1591,7 +1591,7 @@ def ls_tree(
 
     Args:
       repo: Path to the repository
-      tree_ish: Tree id to list
+      treeish: Tree id to list
       outstream: Output stream (defaults to stdout)
       recursive: Whether to recursively list files
       name_only: Only print item name
@@ -1662,7 +1662,7 @@ def update_head(repo, target, detached=False, new_branch=None):
 
     Args:
       repo: Path to the repository
-      detach: Create a detached head
+      detached: Create a detached head
       target: Branch or committish to switch to
       new_branch: New branch to create
     """
@@ -1784,7 +1784,7 @@ def describe(repo):
     """Describe the repository version.
 
     Args:
-      projdir: git repository root
+      repo: git repository
     Returns: a string description of the current git revision
 
     Examples: "gabcdefh", "v0.1" or "v0.1-5-gabcdefh".

dulwich/refs.py

@@ -350,13 +350,13 @@ class RefsContainer(object):
         """
         raise NotImplementedError(self.set_if_equals)
 
-    def add_if_new(self, name, ref):
+    def add_if_new(self, name, ref, committer=None, timestamp=None,
+                   timezone=None, message=None):
         """Add a new reference only if it does not already exist.
 
         Args:
           name: Ref name
           ref: Ref value
-          message: Message for reflog
         """
         raise NotImplementedError(self.add_if_new)