docs: mdox reformat

Author: Tit Petric

docs/Taskfile.yml

@@ -1,11 +1,19 @@
+# Running this taskfile ensures that markdowns are
+# consistently formatted according to mdox rules.
 ---
 version: "3"
 
-# Running this taskfile ensures that markdowns are
-# consistently formatted according to mdox rules.
+vars:
+  root:
+    sh: git rev-parse --show-toplevel
 
 tasks:
-  default:
+  fmt:
     desc: "Run mdox to format markdowns"
     cmds:
       - mdox fmt --no-soft-wraps $(find -name '*.md')
+
+  deps:
+    desc:
+    cmds:
+      - go install github.com/bwplotka/mdox@latest

docs/dev/apidef-oas.md

@@ -10,13 +10,11 @@ Make sure `json` and `bson` tags are added to the fields.
 
 If an `enabled` flag is specified in the OAS contract, make sure a corresponding `disabled` or `enabled` flag is added in the classic API definition.
 
-Also make sure that `disabled`/`enabled` flag toggles the feature on or off. 
+Also make sure that `disabled`/`enabled` flag toggles the feature on or off.
 
 ### Why `disabled` or `enabled` in classic API definition?
 
-Historically, almost every feature/middleware in Tyk is considered enabled by default when value for feature controls are non zero values.
-It is disabled when the feature controls are having zero values.
-For this reason, whenever an existing feature is migrated to OAS, and OAS has an `enabled` flag then a `disabled` flag is added to give explicit control to turn off the feature.
+Historically, almost every feature/middleware in Tyk is considered enabled by default when value for feature controls are non zero values. It is disabled when the feature controls are having zero values. For this reason, whenever an existing feature is migrated to OAS, and OAS has an `enabled` flag then a `disabled` flag is added to give explicit control to turn off the feature.
 
 Please also make sure that the disabled flags are set to true in `APIDefinition.SetDisabledFlags()`, so that it is not enabled in OAS by default.
 
@@ -28,27 +26,29 @@ Ensure OAS fields follow `camelCase` notation for `json` and `bson` tags.
 
 For fields that are required:
 
- 1. Do not use `omitempty` in struct tags.
+1. Do not use `omitempty` in struct tags.
 
- 2. Do not use pointer types for required fields.
+2. Do not use pointer types for required fields.
 
- 3. Add a comment `// required` towards the end of a required field so that automation generates docs accordingly. 
+3. Add a comment `// required` towards the end of a required field so that automation generates docs accordingly.
 
- 4. As a convention, we also try to add the corresponding classic API definition fields in godoc in the following format
-    ```
-    // Tyk classic API definition: `!use_keyless`.
-    ```
-    This might not be perfect at this moment, but we aim to keep this link so that customers find it easier to follow the docs.
+4. As a convention, we also try to add the corresponding classic API definition fields in godoc in the following format
+
+   ```
+   // Tyk classic API definition: `!use_keyless`.
+   ```
+
+   This might not be perfect at this moment, but we aim to keep this link so that customers find it easier to follow the docs.
 
 ## Handle Optional Fields
 
 For optional fields:
 
- 1. Add the `omitempty` tag
+1. Add the `omitempty` tag
+
+2. Use pointer types for structs.
 
- 2. Use pointer types for structs. 
- 
- 3. Make sure that `omitempty` tag is added for slice fields that are optional.
+3. Make sure that `omitempty` tag is added for slice fields that are optional.
 
 ## Add Go Doc Comments
 
@@ -58,29 +58,31 @@ Add comments in Go doc format for each field to enable automated documentation g
 
 Every OAS struct should follow the convention of having `Fill(apidef.APIDefinition)` and `ExtractTo(*apidef.APIDefinition)` methods:
 
- `Fill` populates the struct from a classic API definition.
+`Fill` populates the struct from a classic API definition.
 
- `ExtractTo` extracts the contents of an OAS API definition into a classic API definition.
+`ExtractTo` extracts the contents of an OAS API definition into a classic API definition.
 
 ## Implement Fill Method Pattern
 
 Each `Fill` method should follow this pattern:
 
 ```go
 if u.RateLimit == nil {
-    u.RateLimit = &RateLimit{}
+	u.RateLimit = &RateLimit{}
 }
 
 u.RateLimit.Fill(api)
 if ShouldOmit(u.RateLimit) {
-    u.RateLimit = nil
+	u.RateLimit = nil
 }
 ```
 
 This ensures the field is reset to empty when not configured in the classic API definition.
 
 ### Working with `VersionData`
+
 A `Main` version will be provided that can be used for `Fill`.
+
 ```go
 api.VersionData.Versions[Main]
 ```
@@ -91,17 +93,19 @@ Similarly, follow this pattern with `ExtractTo`:
 
 ```go
 if u.RateLimit == nil {
-    u.RateLimit = &RateLimit{}
-    defer func() {
-        u.RateLimit = nil
-    }()
+	u.RateLimit = &RateLimit{}
+	defer func() {
+		u.RateLimit = nil
+	}()
 }
 
 u.RateLimit.ExtractTo(api)
 ```
 
 ### Working with `VersionData`
+
 There are 2 helper functions for `ExtractTo` that will help to handle `VersionData`. You can use them like this:
+
 ```go
 func (g *GlobalRequestSizeLimit) ExtractTo(api *apidef.APIDefinition) {
 	mainVersion := requireMainVersion(api)
@@ -115,16 +119,14 @@ func (g *GlobalRequestSizeLimit) ExtractTo(api *apidef.APIDefinition) {
 
 ## Write Tests
 
-Write tests for conversion functions. Refer to the example:
-https://github.com/TykTechnologies/tyk/pull/5979/files#diff-222cc254c0c6c09fa0cf50087860b837a0873e2aef3c84ec7d80b1014c149057R97
+Write tests for conversion functions. Refer to the example: https://github.com/TykTechnologies/tyk/pull/5979/files#diff-222cc254c0c6c09fa0cf50087860b837a0873e2aef3c84ec7d80b1014c149057R97
 
 ## Update TestOAS_ExtractTo_ResetAPIDefinition
 
 Maintain and update the list of fields that are not OAS compatible in the `TestOAS_ExtractTo_ResetAPIDefinition` test.
 
 ## Update JSON Schema
 
-Update the JSON schema for the `x-tyk-api-gateway` struct in:
-https://github.com/TykTechnologies/tyk/blob/master/apidef/oas/schema/x-tyk-api-gateway.json
+Update the JSON schema for the `x-tyk-api-gateway` struct in: https://github.com/TykTechnologies/tyk/blob/master/apidef/oas/schema/x-tyk-api-gateway.json
 
-Ensure this schema is updated whenever the OAS API definition is modified.
+Ensure this schema is updated whenever the OAS API definition is modified.