From 6f51f40a5e77c2c6e7ce309fac513778078ba43a Mon Sep 17 00:00:00 2001
From: LandonTClipp <landonclipp@gmail.com>
Date: Fri, 15 Sep 2023 18:12:40 -0500
Subject: [PATCH] Add config examples to migration docs

This fixes #703

Fixing incorrect statement in docs.

It's `inpackage` that controlled whether or not something was placed
next to an interface, not `keeptree`.
---
 docs/configuration.md         | 11 ++++--
 docs/migrating_to_packages.md | 70 ++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 6 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index f2bfcac6..21810355 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -179,8 +179,12 @@ Using different configuration parameters, we can deploy our mocks on-disk in var
         }
         ```
 
-Template Variables
------------------
+Templated Strings
+------------------
+
+mockery configuration makes use of the Go templating system. 
+
+### Variables
 
 !!! note
     Templated variables are only available when using the `packages` config feature.
@@ -201,8 +205,7 @@ Variables that are marked as being templated are capable of using mockery-provid
 | PackageName             | The name of the package from the original interface                                                                                                                                                                                                                                           |
 | PackagePath             | The fully qualified package path of the original interface                                                                                                                                                                                                                                    |
 
-Template functions
-------------------
+### Functions
 
 !!! note
     Templated functions are only available when using the `packages` config feature.
diff --git a/docs/migrating_to_packages.md b/docs/migrating_to_packages.md
index 0b20cbce..acee49d6 100644
--- a/docs/migrating_to_packages.md
+++ b/docs/migrating_to_packages.md
@@ -21,10 +21,76 @@ The existence of the `#!yaml packages:` map in your configuration acts as a feat
 
 The configuration parameters used in `packages` should be considered to have no relation to their meanings in the legacy scheme. It is recommended to wipe out all previous configuration and command-line parameters previously used.
 
-The [configuration docs](configuration.md#packages-config) show the parameters that are available for use in the `packages` scheme. You should only use the parameters shown in this section. Mockery will not prevent you from using the legacy parameter set, but doing so will result in undefined behavior.
+The [configuration docs](configuration.md#parameter-descriptions) show the parameters that are available for use in the `packages` scheme. You should only use the parameters shown in this section. Mockery will not prevent you from using the legacy parameter set, but doing so will result in undefined behavior.
 
 All of the parameters in the config section can be specified at the top level of the config file, which serves as the default values. The `packages` config section defines package-specific config. See some examples [here](features.md#examples).
 
+### Examples
+
+#### Separate `mocks/` directory
+
+Take for example a configuration where you are specifying `all: true` at the top of your repo and you're placing your mocks in a separate `mocks/` directory, mirroring the directory structure of your original repo.
+
+```yaml
+testonly: False
+with-expecter: True
+keeptree: True
+all: True
+```
+
+The equivalent config for `packages` looks like this:
+
+```yaml
+with-expecter: True
+inpackage: True
+dir: mocks/{{ replaceAll .InterfaceDirRelative "internal" "internal_" }} #(1)!
+mockname: "{{.InterfaceName}}"
+outpkg: "{{.PackageName}}"
+filename: "{{.InterfaceName}}.go"
+all: True
+packages:
+  github.com/org/repo:
+    config:
+      recursive: True
+```
+
+1. The use of `replaceAll` is a trick that is done to ensure mocks created for `internal` packages can be imported outside of the mock directory. This retains the behavior of the legacy config.
+
+While the example config provided here is more verbose, that is because we're specifying many non-default values in order to retain strict equivalence for this example. It's recommended to refer to the [configuration parameters](configuration.md#parameter-descriptions) to see the defaults provided.
+
+#### Adjacent to interface
+
+Another common pattern in the legacy config is to place mocks next to the file that defined the interface.
+
+```yaml
+with-expecter: True
+inpackage: True
+all: True
+```
+
+For example, the mock file would be laid out like:
+
+```
+./getter.go
+./mock_Getter.go
+```
+
+The equivalent config would look like:
+
+```yaml
+with-expecter: True
+inpackage: True
+dir: "{{.InterfaceDir}}"
+mockname: "Mock{{.InterfaceName}}"
+outpkg: "{{.PackageName}}"
+filename: "mock_{{.InterfaceName}}.go"
+all: True
+packages:
+  github.com/org/repo:
+    config:
+      recursive: True
+```
+
 `//go:generate` directives
 ----------------------------
 
@@ -38,6 +104,6 @@ The legacy behavior iterated over every `.go` file in your project, called [`pac
 Filesystem Tree Layouts
 ------------------------
 
-The legacy config provided the `keeptree` parameter which, if `#!yaml keeptree: True`, would place the mocks in the same package as your interfaces. Otherwise, it would place it in a separate directory.
+The legacy config provided the `inpackage` parameter which, if `#!yaml inpackage: True`, would place the mocks in the same package as your interfaces. Otherwise, it would place it in a separate directory.
 
 These two layouts are supported in the `packages` scheme. See the relevant docs [here](features.md#layouts).