From 5e8654e0bf9f890bb5ae9f13eb95c1a84f817ff0 Mon Sep 17 00:00:00 2001
From: Brian Tiemann <btman@mac.com>
Date: Tue, 22 Oct 2024 19:08:23 -0400
Subject: [PATCH] Documentation of new and affected models

---
 docs/development/adding-models.md         |  2 +-
 docs/models/dcim/interface.md             |  4 ++++
 docs/models/ipam/vlantranslationpolicy.md | 15 +++++++++++++++
 docs/models/ipam/vlantranslationrule.md   | 17 +++++++++++++++++
 docs/models/virtualization/vminterface.md |  4 ++++
 5 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 docs/models/ipam/vlantranslationpolicy.md
 create mode 100644 docs/models/ipam/vlantranslationrule.md

diff --git a/docs/development/adding-models.md b/docs/development/adding-models.md
index f3aa9cfcc..59c3b0020 100644
--- a/docs/development/adding-models.md
+++ b/docs/development/adding-models.md
@@ -8,7 +8,7 @@ Each model should define, at a minimum:
 
 * A `Meta` class specifying a deterministic ordering (if ordered by fields other than the primary ID)
 * A `__str__()` method returning a user-friendly string representation of the instance
-* A `get_absolute_url()` method returning an instance's direct URL (using `reverse()`)
+* A `get_absolute_url()` method if necessary; a standard version of the method is defined in the `NetBoxFeatureSet` base class, but you will need to provide your own (returning an instance's direct URL using `reverse()`) if not subclassing that base class
 
 ## 2. Define field choices
 
diff --git a/docs/models/dcim/interface.md b/docs/models/dcim/interface.md
index 3667dabd5..869cb8510 100644
--- a/docs/models/dcim/interface.md
+++ b/docs/models/dcim/interface.md
@@ -142,3 +142,7 @@ The configured channel width of a wireless interface, in MHz. This is typically
 ### Wireless LANs
 
 The [wireless LANs](../wireless/wirelesslan.md) for which this interface carries traffic. (Valid for wireless interfaces only.)
+
+### VLAN Translation Policy
+
+The [VLAN translation policy](../ipam/vlantranslationpolicy.md) that applies to this interface (optional).
diff --git a/docs/models/ipam/vlantranslationpolicy.md b/docs/models/ipam/vlantranslationpolicy.md
new file mode 100644
index 000000000..81c9ec0bd
--- /dev/null
+++ b/docs/models/ipam/vlantranslationpolicy.md
@@ -0,0 +1,15 @@
+# VLAN Translation Policies
+
+VLAN translation is a feature that consists of VLAN translation policies and [VLAN translation rules](./vlantranslationrule.md). Many rules can belong to a policy, and each rule defines a mapping of a local to remote VLAN ID (VID). A policy can then be assigned to an [Interface](../dcim/interface.md) or [VMInterface](../virtualization/vminterface.md), and all VLAN translation rules associated with that policy will be visible in the interface details.
+
+Within a policy, local VIDs and remote VIDs are independently unique. Thus, two different policies may contain rules that define a local VID of 100 or a remote VID of 200, but two rules within a single policy with `local_vid=100` or with `remote_vid=200` are prohibited.
+
+## Fields
+
+### Name
+
+A unique human-friendly name.
+
+### Description
+
+A brief description of the policy and/or its purpose.
diff --git a/docs/models/ipam/vlantranslationrule.md b/docs/models/ipam/vlantranslationrule.md
new file mode 100644
index 000000000..8a77c8919
--- /dev/null
+++ b/docs/models/ipam/vlantranslationrule.md
@@ -0,0 +1,17 @@
+# VLAN Translation Rules
+
+See [VLAN translation policies](./vlantranslationpolicy.md) for an overview of the VLAN Translation feature.
+
+## Fields
+
+### Policy
+
+The [VLAN Translation Policy](./vlantranslationpolicy.md) to which this rule belongs.
+
+### Local VID
+
+VLAN ID (1-4094) in the local network which is to be translated to a remote VID.
+
+### Remote VID
+
+VLAN ID (1-4094) in the remote network to which the local VID will be translated.
diff --git a/docs/models/virtualization/vminterface.md b/docs/models/virtualization/vminterface.md
index d923bdd5d..1e022b091 100644
--- a/docs/models/virtualization/vminterface.md
+++ b/docs/models/virtualization/vminterface.md
@@ -56,3 +56,7 @@ The tagged VLANs which are configured to be carried by this interface. Valid onl
 ### VRF
 
 The [virtual routing and forwarding](../ipam/vrf.md) instance to which this interface is assigned.
+
+### VLAN Translation Policy
+
+The [VLAN translation policy](../ipam/vlantranslationpolicy.md) that applies to this interface (optional).