Re: [PATCH 04/20] git-p4: improve consistency of docstring formatting

[Eric Sunshine <sunshine@sunshineco.com>]

On Wed, Jan 12, 2022 at 8:47 AM Joel Holdsworth <jholdsworth@nvidia.com> wrote:
> This patch attempts to improve the consistency of the docstrings by
> making the following changes:
>
>   - Rewraps all docstrings to a 79-character column limit.
>   - Adds a full stop at the end of every docstring.
>   - Removes any spaces after the opening triple-quotes of all
>     docstrings.
>   - Sets the hanging indent of multi-line docstrings to 3-spaces.
>   - Ensures that the closing triple-quotes of multi-line docstrings are
>     always on a new line indented by a 3-space indent.

A couple very minor comments below... probably not worth a re-roll.

> Signed-off-by: Joel Holdsworth <jholdsworth@nvidia.com>
> ---
> diff --git a/git-p4.py b/git-p4.py
> @@ -271,20 +271,20 @@ def run_git_hook(cmd, param=[]):
>  def run_hook_command(cmd, param):
>      """Executes a git hook command

Missing full-stop (as described by the commit message)?

> -       cmd = the command line file to be executed. This can be
> -       a file that is run by OS association.
>
> -       param = a list of parameters to pass to the cmd command
> +       cmd -- the command line file to be executed.  This can be a file that
> +           is run by OS association.
> +
> +       param -- a list of parameters to pass to the cmd command

These were changed from `=` to `--` (double hyphen), which is fine, but...

> @@ -715,21 +718,22 @@ def getGitTags():
>  def parseDiffTreeEntry(entry):
>      """Parses a single diff tree entry into its component elements.
>
> +       See git-diff-tree(1) manpage for details about the format of the diff
> +       output. This method returns a dictionary with the following elements:
> +
> +       src_mode - The mode of the source file
> +       dst_mode - The mode of the destination file
> +       src_sha1 - The sha1 for the source file
> +       dst_sha1 - The sha1 fr the destination file
> +       status - The one letter status of the diff (i.e. 'A', 'M', 'D', etc)
> +       status_score - The score for the status (applicable for 'C' and 'R'
> +                      statuses). This is None if there is no score.
> +       src - The path for the source file.
> +       dst - The path for the destination file. This is only present for
> +             copy or renames. If it is not present, this is None.

... these just use `-` (single hyphen).

> +       If the pattern is not matched, None is returned.
> +       """