Add tips, tricks, and pitfalls to README

jsh9 · Jan 12, 2025 · 64ef923 · 64ef923
1 parent fe188f4
commit 64ef923
Show file tree

Hide file tree

Showing 2 changed files with 124 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -43,14 +43,18 @@ The corresponding Github repository of _pydoclint_ is:
 - [2. Usage](#2-usage)
   - [2.1. As a native command line tool](#21-as-a-native-command-line-tool)
   - [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin)
-  - [2.3. As a pre-commit hook](#23-as-a-pre-commit-hook)
-    - [2.3.1. Native mode](#231-native-mode)
-    - [2.3.2. As a _flake8_ plugin](#232-as-a-flake8-plugin)
-  - [2.4. Native vs _flake8_](#24-native-vs-flake8)
+  - [2.3. Native vs _flake8_](#23-native-vs-flake8)
+  - [2.4. As a pre-commit hook](#24-as-a-pre-commit-hook)
+    - [2.4.1. Native mode](#241-native-mode)
+    - [2.4.2. As a _flake8_ plugin](#242-as-a-flake8-plugin)
   - [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint)
   - [2.6. How to ignore certain violations in _flake8_ mode](#26-how-to-ignore-certain-violations-in-flake8-mode)
+  - [2.7. Additional tips, tricks, and pitfalls](#27-additional-tips-tricks-and-pitfalls)
+    - [2.7.1. How to _not_ document certain functions?](#271-how-to-not-document-certain-functions)
+    - [2.7.2. How to gradually adopt _pydoclint_?](#272-how-to-gradually-adopt-pydoclint)
+    - [2.7.3. Pitfall: default values of arguments](#273-pitfall-default-values-of-arguments)
 - [3. Style violation codes](#3-style-violation-codes)
-- [4. Notes for users](#4-notes-for-users)
+- [4. Additional notes for users](#4-additional-notes-for-users)
 - [5. Notes for developers](#5-notes-for-developers)
 
 <!--TOC-->
@@ -95,14 +99,29 @@ flake8 --select=DOC <FILE_OR_FOLDER>
 If you don't include `--select=DOC` in your command, _flake8_ will also run
 other built-in _flake8_ linters on your code.
 
-### 2.3. As a pre-commit hook
+### 2.3. Native vs _flake8_
+
+Should you use _pydoclint_ as a native command line tool or a _flake8_ plugin?
+Here's comparison:
+
+|                 | Pros                                     | Cons                                                          |
+| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
+| Native tool     | Slightly faster; supports "baseline" [*] | No inline or project-wide omission support right now [**]     |
+| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
+
+\*) "Baseline" allows you to log the current violation state of your existing
+project, making adoption of _pydoclint_ much easier.
+
+\*\*) This feature may be added in the near future
+
+### 2.4. As a pre-commit hook
 
 _pydoclint_ can be use as a [pre-commit hook](https://pre-commit.com/), both in
 the "native" mode or as a _flake8_ plugin.
 
 To use it, put the following in your `.pre-commit-config.yaml` file:
 
-#### 2.3.1. Native mode
+#### 2.4.1. Native mode
 
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
@@ -115,7 +134,7 @@ To use it, put the following in your `.pre-commit-config.yaml` file:
 (Replace `<latest_tag>` with the latest release tag in
 https://github.com/jsh9/pydoclint/releases)
 
-#### 2.3.2. As a _flake8_ plugin
+#### 2.4.2. As a _flake8_ plugin
 
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
@@ -125,21 +144,6 @@ https://github.com/jsh9/pydoclint/releases)
       args: [--style=google, --check-return-types=False]
 ```
 
-### 2.4. Native vs _flake8_
-
-Should I use _pydoclint_ as a native command line tool or a _flake8_ plugin?
-Here's comparison:
-
-|                 | Pros                                     | Cons                                                          |
-| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
-| Native tool     | Slightly faster; supports "baseline" [*] | No inline or project-wide omission support right now [**]     |
-| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
-
-\*) "Baseline" allows you to log the current violation state of your existing
-project, making adoption of _pydoclint_ much easier.
-
-\*\*) This feature may be added in the near future
-
 ### 2.5. How to configure _pydoclint_
 
 _pydoclint_ offers many
@@ -154,6 +158,40 @@ Please read this page for instructions on configuring _pydoclint_:
 Please read this page:
 [How to ignore certain violations](https://jsh9.github.io/pydoclint/how_to_ignore.html)
 
+### 2.7. Additional tips, tricks, and pitfalls
+
+#### 2.7.1. How to _not_ document certain functions?
+
+If you don't write any docstring for a function, _pydoclint_ will not check it.
+
+Also, if you write a docstring with only a description (without the argument
+section, the return section, etc.), _pydoclint_ will not check this docstring,
+because the `--skip-checking-short-docstrings` is `True` by default. (You can
+set it to `False`.)
+
+#### 2.7.2. How to gradually adopt _pydoclint_?
+
+_pydoclint_ provides a "baseline" feature that allows you to log the current
+violation state of your existing project. You'll only need to fix new style
+violations, and you can fix the "baseline" violations later.
+
+You can use "baseline" with these 3 config options:
+
+- `--baseline`
+- `--generate-baseline`
+- `--auto-regenerate-baseline`
+
+For more details, please read the
+[documentations on these options](https://jsh9.github.io/pydoclint/config_options.html#18---baseline).
+
+#### 2.7.3. Pitfall: default values of arguments
+
+_pydoclint_ does not like adding default values of arguments in the docstring,
+even if this style is allowed in the numpy docstring style guide.
+
+For more rationale, please read
+[this page](https://jsh9.github.io/pydoclint/notes_for_users.html#3-notes-on-writing-type-hints).
+
 ## 3. Style violation codes
 
 _pydoclint_ currently has 7 categories of style violation codes:
@@ -169,7 +207,7 @@ _pydoclint_ currently has 7 categories of style violation codes:
 For detailed explanations of each violation code, please read this page:
 [_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html).
 
-## 4. Notes for users
+## 4. Additional notes for users
 
 If you'd like to use _pydoclint_ for your project, it is recommended that you
 read these additional notes

diff --git a/docs/index.md b/docs/index.md
@@ -43,14 +43,18 @@ The corresponding Github repository of _pydoclint_ is:
 - [2. Usage](#2-usage)
   - [2.1. As a native command line tool](#21-as-a-native-command-line-tool)
   - [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin)
-  - [2.3. As a pre-commit hook](#23-as-a-pre-commit-hook)
-    - [2.3.1. Native mode](#231-native-mode)
-    - [2.3.2. As a _flake8_ plugin](#232-as-a-flake8-plugin)
-  - [2.4. Native vs _flake8_](#24-native-vs-flake8)
+  - [2.3. Native vs _flake8_](#23-native-vs-flake8)
+  - [2.4. As a pre-commit hook](#24-as-a-pre-commit-hook)
+    - [2.4.1. Native mode](#241-native-mode)
+    - [2.4.2. As a _flake8_ plugin](#242-as-a-flake8-plugin)
   - [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint)
   - [2.6. How to ignore certain violations in _flake8_ mode](#26-how-to-ignore-certain-violations-in-flake8-mode)
+  - [2.7. Additional tips, tricks, and pitfalls](#27-additional-tips-tricks-and-pitfalls)
+    - [2.7.1. How to _not_ document certain functions?](#271-how-to-not-document-certain-functions)
+    - [2.7.2. How to gradually adopt _pydoclint_?](#272-how-to-gradually-adopt-pydoclint)
+    - [2.7.3. Pitfall: default values of arguments](#273-pitfall-default-values-of-arguments)
 - [3. Style violation codes](#3-style-violation-codes)
-- [4. Notes for users](#4-notes-for-users)
+- [4. Additional notes for users](#4-additional-notes-for-users)
 - [5. Notes for developers](#5-notes-for-developers)
 
 <!--TOC-->
@@ -95,14 +99,29 @@ flake8 --select=DOC <FILE_OR_FOLDER>
 If you don't include `--select=DOC` in your command, _flake8_ will also run
 other built-in _flake8_ linters on your code.
 
-### 2.3. As a pre-commit hook
+### 2.3. Native vs _flake8_
+
+Should you use _pydoclint_ as a native command line tool or a _flake8_ plugin?
+Here's comparison:
+
+|                 | Pros                                     | Cons                                                          |
+| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
+| Native tool     | Slightly faster; supports "baseline" [*] | No inline or project-wide omission support right now [**]     |
+| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
+
+\*) "Baseline" allows you to log the current violation state of your existing
+project, making adoption of _pydoclint_ much easier.
+
+\*\*) This feature may be added in the near future
+
+### 2.4. As a pre-commit hook
 
 _pydoclint_ can be use as a [pre-commit hook](https://pre-commit.com/), both in
 the "native" mode or as a _flake8_ plugin.
 
 To use it, put the following in your `.pre-commit-config.yaml` file:
 
-#### 2.3.1. Native mode
+#### 2.4.1. Native mode
 
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
@@ -115,7 +134,7 @@ To use it, put the following in your `.pre-commit-config.yaml` file:
 (Replace `<latest_tag>` with the latest release tag in
 https://github.com/jsh9/pydoclint/releases)
 
-#### 2.3.2. As a _flake8_ plugin
+#### 2.4.2. As a _flake8_ plugin
 
 ```yaml
 - repo: https://github.com/jsh9/pydoclint
@@ -125,21 +144,6 @@ https://github.com/jsh9/pydoclint/releases)
       args: [--style=google, --check-return-types=False]
 ```
 
-### 2.4. Native vs _flake8_
-
-Should I use _pydoclint_ as a native command line tool or a _flake8_ plugin?
-Here's comparison:
-
-|                 | Pros                                     | Cons                                                          |
-| --------------- | ---------------------------------------- | ------------------------------------------------------------- |
-| Native tool     | Slightly faster; supports "baseline" [*] | No inline or project-wide omission support right now [**]     |
-| _flake8_ plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
-
-\*) "Baseline" allows you to log the current violation state of your existing
-project, making adoption of _pydoclint_ much easier.
-
-\*\*) This feature may be added in the near future
-
 ### 2.5. How to configure _pydoclint_
 
 _pydoclint_ offers many
@@ -154,6 +158,40 @@ Please read this page for instructions on configuring _pydoclint_:
 Please read this page:
 [How to ignore certain violations](https://jsh9.github.io/pydoclint/how_to_ignore.html)
 
+### 2.7. Additional tips, tricks, and pitfalls
+
+#### 2.7.1. How to _not_ document certain functions?
+
+If you don't write any docstring for a function, _pydoclint_ will not check it.
+
+Also, if you write a docstring with only a description (without the argument
+section, the return section, etc.), _pydoclint_ will not check this docstring,
+because the `--skip-checking-short-docstrings` is `True` by default. (You can
+set it to `False`.)
+
+#### 2.7.2. How to gradually adopt _pydoclint_?
+
+_pydoclint_ provides a "baseline" feature that allows you to log the current
+violation state of your existing project. You'll only need to fix new style
+violations, and you can fix the "baseline" violations later.
+
+You can use "baseline" with these 3 config options:
+
+- `--baseline`
+- `--generate-baseline`
+- `--auto-regenerate-baseline`
+
+For more details, please read the
+[documentations on these options](https://jsh9.github.io/pydoclint/config_options.html#18---baseline).
+
+#### 2.7.3. Pitfall: default values of arguments
+
+_pydoclint_ does not like adding default values of arguments in the docstring,
+even if this style is allowed in the numpy docstring style guide.
+
+For more rationale, please read
+[this page](https://jsh9.github.io/pydoclint/notes_for_users.html#3-notes-on-writing-type-hints).
+
 ## 3. Style violation codes
 
 _pydoclint_ currently has 7 categories of style violation codes:
@@ -169,7 +207,7 @@ _pydoclint_ currently has 7 categories of style violation codes:
 For detailed explanations of each violation code, please read this page:
 [_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html).
 
-## 4. Notes for users
+## 4. Additional notes for users
 
 If you'd like to use _pydoclint_ for your project, it is recommended that you
 read these additional notes