wip: Working on better developer docs

markdown/dev/reference/api/pattern/samplemodels/en.md

@@ -1,42 +1,70 @@
 ---
-title: sampleModels()
+title: Pattern.sampleModels()
 ---
 
+A pattern's `sampleModels()` method will *sample* a pattern for a list of
+models you pass to it. It will draft different iterations of the pattern,
+using the measurements for each model you pass to it.
+
+<Tip>
+The goal of model sampling is to verify that a pattern grades correctly up and down as sizes change.
+</Tip>
+
+<Note>This method is chainable as it returns the Pattern object</Note>
+
+<Tip>
+
+###### Anchor your samples
+
+If you add a point named `anchor` to your pattern part, the different samples
+will be anchored on this point.
+
+In other words, for each sample, the anchor point will be kept in the same location.
+
+</Tip>
+
+## Pattern.sampleModels() signature
+
 ```js
 Pattern pattern.sampleModels(object models, string focus)
 ``` 
-
-Samples a pattern for a number of models you pass to it.
-
-The goal of model sampling is to verify that a pattern grades correctly up and down as sizes change.
+The models object you pass as the first parameter should be structured as such:
+
+```js
+{
+ modelName1: {
+   measurement1: valueInMm,
+   measurement2: valueInMm,
+   // ...
+ },
+ modelName2: {
+   measurement1: valueInMm,
+   measurement2: valueInMm,
+   // ...
+ },
+ // ...
+}
+```
+
+The (optional) string you can pass as the second parameter should hold the 
+key of one of the models in the first parameter. In our example above, it
+could hold `modelName2` for example.
+
+By passing this second parameter, you can put the *focus* on one of the models, 
+which will influence the render style, and make it 
+easier to see a comparison between a given set of measrurements, and the rest.
+
+Alternatively, you can use the `Pattern.sample()` method and set `settings.sample.focus` to the key
+identifying your model in the models object.
+
+## Pattern.sampleModels() example
 
 ```js
-import freesewing from "@freesewing/core"
 import Aaron from "@freesewing/aaron"
 import models from "@freesewing/models"
 
-let aaron = new Aaron({
-  settings: {
-    embed: true,
-    measurements: models.manSize38
-  }, 
-})
+const Aaron = new Aaron()
 
-let svg = aaron.sampleModels(models, "manSize38").render()
+const svg = aaron.sampleModels(models, "manSize38").render()
 ``` 
 
-<Tip>
-
-###### Model focus: Making a comparison
-
-When sampling models, you can put the *focus* on one of the models, thereby making it 
-easier to see a comparison between a given set of measrurements, and the rest.
-
-To do so, pass a second parameter to the `sampleModels()` method. This should be
-the key of the model in the models object for that model you want the focus to be on.
-
-Alternatively, you can use the `sample()` method and set `settings.sample.focus` to the key
-identifying your model in the models object.
-
-</Tip>
-