wip: More improvements on dev docs

markdown/dev/reference/api/part/copy/en.md

@@ -1,19 +0,0 @@
----
-title: copy()
----
-
-```js
-Part part.copy(Part original)
-```
-
-This will copy the points, paths, and snippets from a part you pass into it.
-
-<Note>
-
-This method is used internally, you are unlikely to need this.
-
-If you want one part to build on another, you should set 
-up [part inheritance](/advanced/inject)  in your pattern's [configuration](../config) file.
-
-</Note>
-

markdown/dev/reference/api/part/en.md

@@ -3,15 +3,19 @@ title: Part
 order: 20
 ---
 
-Part objects hold the actual information, and together they make up your pattern.
+The `Part` object in FreeSewing's core library holds all data and logic of a pattern part. 
+A pattern part is what holds the actual information about points and paths,
+and multiple parts together typically make up a pattern.
 
-Each Part object comes with the following properties:
+## Part properties
 
- - `paths` : A plain object to store your paths in
+| Property | Description |
- - `points` : A plain object to store your points in
+| --------:| ----------- |
- - `render` : A flag that controls whether to include the part in the render output
+| `paths` | A plain object to store your paths in |
- - `snippets` : A plain object to store your snippets in
+| `points` |  A plain object to store your points in |
+| `render` |  A flag that controls whether to include the part in the render output |
+| `snippets` | A plain object to store your snippets in |
 
-In addition, a Part object exposes the following methods:
+## Part methods
 
 <ReadMore list />

markdown/dev/reference/api/part/getid/en.md

@@ -1,13 +1,34 @@
 ---
-title: getId()
+title: Part.getId()
 ---
 
+A part's `getId()` method will return an integer the can be used as an 
+ID Points/Paths/Snippets. This method will ensure the ID is unique be
+keeping an internal record of the ID that have been used. 
+It is typically used when programatically adding points, paths, or snippets.
+
+## Part.getId() signature
+
 ```js
 int part.getId(prefix='')
 ```
-Returns a integer as an available ID that you can use as for Points/Paths/Snippets.
 
-Takes an options `prefix` to prefix the ID with.
+This methiod takes an optional parameter that will be used as a prefix for the ID.
+
+## Part.getId() example
+
+```js
+export default function (part) {
+  const { Point, points } = part.shorthand()
+
+  for (let i=0;i<10;i++) {
+    const id= part.getId()
+    points[id] = new Point(i*10, i*10)
+  }
+
+  // You would do more useful stuff before returning
+  return part
+}
+```
 
-This is typically used when adding points programmatically.
 

markdown/dev/reference/api/part/raise/debug/en.md

@@ -1,12 +1,10 @@
 ---
-title: raise.debug()
+title: Part.raise.debug()
 ---
 
-```js
+A part's `raise.debug()` method will log a debug-level event.
-raise.debug(data)
+Debug events are typically used to pass information to pattern developers
-```
+so that can troubleshoot issues with the pattern.
-
-The `raise.debug()` method adds an event of type `debug` to the pattern.
 
 What happens with this data is entirely up to the frontend developer.
 As such, data can by anything you like. A string is common, but you
@@ -18,3 +16,23 @@ use in your frontend.
 All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
 
 </Tip>
+
+## Part.raise.debug() signature
+
+```js
+raise.debug(data)
+```
+
+## Part.raise.debug() example
+
+```js
+export default function (part) {
+  const { raise } = part.shorthand()
+
+  raise.debug('Entered the draft method of partmyPart')
+  
+  // You would do more useful stuff before returning
+  return part
+}
+```
+

markdown/dev/reference/api/part/raise/en.md

@@ -1,9 +1,19 @@
 ---
-title: raise methods
+title: Part raise methods
 ---
 
-The various `raise` methods are used to bring information to the attention
+A part's different `raise` methods are used to bring information to the attention
-of the user, or developer.
+of the user, or developer. You can think of them as logging methods the register
+data.
+
+<Warning>
+
+##### FreeSewing v3 breaking changes
+
+This behavior is likely to change in FreeSewing v3. Refer to [the
+roadmap](https://github.com/freesewing/freesewing/discussions/1278) for details.
+
+</Warning>
 
 There are four different types of information with their own method: 
 

markdown/dev/reference/api/part/raise/error/en.md

@@ -1,27 +1,35 @@
 ---
-title: raise.error()
+title: Part.raise.error()
 ---
 
-```js
+A part's `raise.error()` method will log a error-level event.
-raise.error(data)
+Unlike other raised events which have no side-effects, if there is one or more
-```
-
-The `raise.error()` method adds an event of type `error` to the pattern.
-
-<Note>
-
-##### Raising an error will prevent the pattern from being completed
-
-Unlike other events, which have no side-effects, if there is one or more
 events of type `error`, the pattern will not be completed.
-
+In other words, you should only use this when end up in a situation
-In other words, you should only use this when the situation is unrecoverable.
+you cannot recover from.  If not, [raise a warning](/reference/api/part/raise/warning).
-If not, [raise a warning](/reference/api/part/raise/warning).
-
-</Note>
 
 <Tip>
 
 All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
 
 </Tip>
+
+## Part.raise.error() signature
+
+```js
+raise.error(data)
+```
+
+## Part.raise.error() example
+
+```js
+export default function (part) {
+  const { raise, measurements } = part.shorthand()
+
+  if (measurements.hips > measurements.chest) {
+    raise.warning('Chest circumference smaller than hip circumference is currently unsupported. Aborting.')
+    return part
+  } 
+}
+```
+

markdown/dev/reference/api/part/raise/info/en.md

@@ -1,12 +1,10 @@
 ---
-title: raise.info()
+title: Part.raise.info()
 ---
 
-```js
+A part's `raise.info()` method will log a ingo-level event.
-raise.info(data)
+Info events are typically used to pass information to users
-```
+that is informative to them.
-
-The `raise.info()` method adds an event of type `info` to the pattern.
 
 What happens with this data is entirely up to the frontend developer.
 As such, data can by anything you like. A string is common, but you
@@ -18,3 +16,22 @@ use in your frontend.
 All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
 
 </Tip>
+
+## Part.raise.info() signature
+
+```js
+raise.info(data)
+```
+
+## Part.raise.info() example
+
+```js
+export default function (part) {
+  const { raise, options } = part.shorthand()
+
+  if (options.shortSleeves) { 
+    raise.info('Not drafting french cuffs because you opted for short sleeves')
+    return part
+  }
+}
+```

markdown/dev/reference/api/part/raise/warning/en.md

@@ -1,12 +1,11 @@
 ---
-title: raise.warning()
+title: Part.raise.warning()
 ---
 
-```js
+A part's `raise.warning()` method will log a warning-level event.
-raise.warning(data)
+Warning events are typically used to pass information to pattern developers
-```
+so that can troubleshoot issues with the pattern, or users to warn them
-
+that something is sub-optimal.
-The `raise.warning()` method adds an event of type `warning` to the pattern.
 
 What happens with this data is entirely up to the frontend developer.
 As such, data can by anything you like. A string is common, but you
@@ -18,3 +17,28 @@ use in your frontend.
 All raise methods are available via [the shorthand method](/reference/api/part/shorthand)
 
 </Tip>
+
+## Part.raise.warning() signature
+
+```js
+raise.warning(data)
+```
+
+## Part.raise.warning() example
+
+```js
+export default function (part) {
+  const { raise, measurements } = part.shorthand()
+
+  if (measurements.hips > measurements.chest) {
+    raise.warning(`
+      Chest circumference is smaller than hip circumference. 
+      This might lead to unexpected results
+    `)
+  } 
+
+  // You would do more useful stuff before returning
+  return part
+}
+```
+

markdown/dev/reference/api/part/shorthand/en.md

@@ -1,63 +1,80 @@
 ---
-title: shorthand()
+title: Part.shorthand()
 ---
 
+A part's `shorthand()` method provides easy access to a number of
+internal objects and properties. It does so be returning an object
+that contains all you need to draft your pattern parts. It is 
+typically combined with object destructuring to pull out those
+properties you need.
+
+As the name implies, this method can save you a bunch of typing, and keep your
+code concise. We highly recommend you use it.
+
+## Part.shorthand() signature
+
 ```js
 object Part.shorthand();
 ```
 
-This method returns a plain object with the following properties:
+The `Part.shorthand()` method returns a plain object with the following properties:
 
-  - `complete` = `pattern.settings.complete`
+| Property | Description |
-  - `events` : An object holding the raised events (see `raise`)
+| --------:| ----------- |
-  - `final` : `true` is this is a full draft, or `false` if this is a sample.
+| `config` | The pattern configuration |
-  - `macro` : The macro runner
+| `complete` | Holds `pattern.settings.complete` |
-  - `measurements` = `pattern.settings.measurements`
+| `events` | An object holding the raised events (see [Part.raise](/reference/api/part/raise/)) |
-  - `paperless` = `pattern.settings.paperless`
+| `final` | `true` is this is a full draft, or `false` if this is a sample. |
-  - `Path` : the [Path](/reference/api/path) constructor
+| `macro` | The macro runner. See [the macros documentation](/reference/macros/) |
-  - `paths` = `part.paths`
+| `measurements` | Holds `pattern.settings.measurements` |
-  - `Point` : the [Point](/reference/api/point) constructor
+| `paperless` | Holds `pattern.settings.paperless` |
-  - `points` = `part.points`
+| `Path` | The [Path constructor](/reference/api/path) |
-  - `Snippet` : the [Snippet](/reference/api/snippet) constructor
+| `paths` | Holds `part.paths` |
-  - `snippets` = `part.snippets`
+| `Point` | The [Point constructor](/reference/api/point) |
-  - `options` = `pattern.settings.options`
+| `points` | Holds `part.points` |
-  - `raise` : An object holding the various methods that allow you to [raise events](/reference/api/part/raise/)
+| `Snippet` | The [Snippet constructor](/reference/api/snippet) |
-  - `sa` = `pattern.settings.sa`
+| `snippets` | Holds `part.snippets` |
-  - `store` = `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts
+| `options` | Holds `pattern.settings.options` |
-  - `utils` : A [Utils](/reference/api/utils) instance with utility methods
+| `raise` | Holds [Part.raise](/reference/api/part/raise/) thus giving you access to the various raise methods |
-  - `units` : A context-aware version of `utils.units`
+| `sa` | Holds `pattern.settings.sa` |
+| `store` | Holds `pattern.store`, a [Store](/reference/api/store) instance that is shared across parts |
+| `utils` | A [Utils](/reference/api/utils) instance with utility methods |
+| `units` | A context-aware version of `utils.units` |
 
-As the name implies, this method can save you a bunch of typing, and keep your
+## Part.shorthand() example
-code concise. We highly recommend it. Below are some examples:
 
 ```js{16}
 // You could write this:
 part.points.from = new part.Point(
-  pattern.measurements.chestCircumference / 2, 
+  pattern.measurements.chest / 2, 
-  pattern.options.armholeDepth);
+  pattern.options.armholeDepth
+)
 
 part.points.to = new part.Point(
   part.points.from.x + pattern.settings.sa, 
-  part.points.from.y);
+  part.points.from.y
+)
 
 part.paths.example = new part.Path()
   .move(parts.points.from)
-  .line(parts.points.to);
+  .line(parts.points.to)
 
-// Or use shorthand:
+// Or use shorthand:  
-let { Point, points, measurements, options, sa } = part.shorthand();
+const { Point, points, measurements, options, sa } = part.shorthand()
 
 points.from = new Point(
-  measurements.chestCircumference / 2, 
+  measurements.chest / 2, 
-  options.armholeDepth);
+  options.armholeDepth
+)
 
 points.to = new part.Point(
   points.from.x + sa, 
-  points.from.y);
+  points.from.y
+)
 
 paths.example = new Path()
   .move(points.from)
-  .line(points.to);
+  .line(points.to)
 ```
 
 <Tip>

markdown/dev/reference/api/part/units/en.md

@@ -1,12 +1,11 @@
 ---
-title: units()
+title: Part.units()
 ---
 
-```js
+A part's `units()` method will formats a float you pass it, which should
-string part.units(float number)
+represent a value in mm, into the units requested by the user.
-```
+The returned value is to be used in presentation only, as it will be 
-
+a string that includes the user's units.
-Formats input (in mm) as the units requested by the user.
 
 <Tip>
 
@@ -20,3 +19,19 @@ let { units } = part.shorthand();
 
 </Tip>
 
+## Part.units() signature
+
+```js
+string part.units(float number)
+```
+
+## Part.units() example
+
+```js
+export default function (part) {
+  const { raise, units, measurements } = part.shorthand()
+
+  raise.info(`Pattern drafted for a ${units(measurements.chest)} chest`)
+}
+```
+

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

@@ -1,20 +0,0 @@
----
-title: Pattern.apply()
----
-
-A pattern's `apply()` method merges the settings passed to it with 
-the current pattern settings. It is used internally to merge the 
-settings that are passed to the pattern constructor with the default settings.
-
-<Note>This method is chainable as it returns the Pattern object</Note>
-
-## Pattern.apply() signature
-
-```js
-Pattern pattern.apply(object settings)
-``` 
-
-<Note>
-You are unlikely to ever user this method directly.
-</Note>
-

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

@@ -1,47 +0,0 @@
----
-title: Pattern.needs()
----
-
-A pattern's `needs()` method will return `true` or `false` 
-depending on whether a pattern part is a requirement for the 
-pattern to be drafted in its current configuration. In other
-words, it will return `true` of the part is *needed*. 
-
-A part is needed if:
-
- - it is requested by the user in [the `only` pattern setting](/reference/settings/only/)
- - it is a dependency of a part requested by the user in [the `only` pattern setting](/reference/settings/only/)
- - [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden
-
-<Note>
-
-You don't typically use this method. Instead, you configure part
-dependencies in your [configuration file](/reference/config/).
-
-</Note>
-
-## Pattern.needs() signature
-
-```js
-bool pattern.needs(string partName)
-``` 
-
-## Pattern.needs() example
-
-```js
-import Aaron from "@freesewing/aaron"
-import models from "@freesewing/models"
-
-const pattern = new Aaron({
-  settings: {
-    embed: true,
-  },
-  measurements: models.manSize38
-})
-
-if (pattern.needs('front')) console.log('Front is needed')
-else console.log('Front is not needed')
-``` 
-
-
-

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

@@ -1,44 +0,0 @@
----
-title: wants()
----
-
-A pattern's `wants()` method will return `true` or `false` 
-depending on whether a pattern part is requested in the 
-current pattern configuration. In other words, it will 
-return `true` of the part is *wanted* by the user. 
-
-A part is wanted if:
-
- - it is requested by the user in [the `only` pattern setting](/reference/settings/only/)
- - [the `only` pattern setting](/reference/settings/only/) is not set or is `false`, and the part is not hidden
-
-<Note>
-
-You don't typically use this method. Instead, you configure part
-dependencies in your [configuration file](/reference/config/).
-
-</Note>
-
-## Pattern.wants() signature
-
-```js
-bool pattern.wants(string partName)
-``` 
-
-## Pattern.wants() example
-
-```js
-import Aaron from "@freesewing/aaron"
-import models from "@freesewing/models"
-
-const pattern = new Aaron({
-  settings: {
-    embed: true,
-  },
-  measurements: models.manSize38
-})
-
-if (pattern.wants('front')) console.log('Front is wanted')
-else console.log('Front is not wanted')
-``` 
-

markdown/dev/reference/api/svg/en.md

@@ -11,7 +11,7 @@ While the methods exposed by this object are only used internally,
 its attributes are useful for situations where you
 want to develop a plugin, or use a custom layout:
 
-## Properties
+## Svg properties
 
 <ReadMore list />