CORD-2356: Update xproto documentation on model options
Change-Id: I731ca82fc89a0632a6c4ebe1558fe50859d822db
diff --git a/docs/dev/xproto.md b/docs/dev/xproto.md
index 68fb986..8791df2 100644
--- a/docs/dev/xproto.md
+++ b/docs/dev/xproto.md
@@ -98,13 +98,73 @@
### Model Options
-Options declare information about models. They can be declared for individual models, or at the top level in the xproto definition, in which case they are inherited by all of the models in that definition.
+Model Options declare information about models. They can be declared for individual models, or at the top level in the xproto definition, in which case they are inherited by all of the models in the file, unless they are overridden by a particular model.
+
+Currently supported model options include: `name`, `app_label`, `verbose_name`, `legacy`, `tosca_description`, `validators`, `plural`, `singular`, and `gui_hidden`.
+
+The name option is a short name used to refer to your service. For example, in the Virtual Subscriber Gateway service, the name option is set to `vSG`.
```protobuf
-option app_label = "core";
+option name = "vSG"
```
-Currently supported model options include: `app_label`, `skip_init`, `skip_django`, `tosca_description`, `validators`, `plural`, `singular`, and `gui_hidden`.
+The app\_label option is a short programmatic name that does not need to be easily understood by humans. It should not include whitespaces, and should preferrably be all lowercase. If app\_label is not specified, then its value defaults to the name option described above.
+
+```protobuf
+option app_label = "vsg"
+```
+
+The verbose\_name option contains a short description of the service.
+
+```protobuf
+option verbose_name = "Virtual Subscriber Gateway Service";
+```
+
+
+```protobuf
+option app_label = "legacy"
+```
+
+The legacy option is for services that require custom Python code in their
+generated models. Without this option set, for any given model (`VSGService`) the
+toolchain generates model classes in a self-contained file (`vsgservice.py`).
+With this option set, the toolchain generates the models in a file called
+`vsgservice_decl.py`. All of the models in this file have the suffix `_decl`.
+It is then up to the service developer to provide the final models. The code below gives
+an example of custom models that inherit from such intermediate `decl` models:
+
+```python
+class VSGService(VSGService__decl):
+ def __xos_base_save(self, *args, **kwargs):
+ self.prop1 = self.prop2 + self.prop3
+ pass
+```
+
+You can use the xproto `service_extender` target to generate a stub for your
+final model definitions.
+
+The plural and singular options provide the grammatically correct plural and singular forms of your model name to ensure that autogenerated API endpoints are valid.
+
+```protobuf
+option singular = "slice" # Singular of slice is not slouse, as computed by Python's pattern.en library
+
+option plural = "ports" # Plural of ports is not portss
+```
+
+The tosca\_description option is a description for the service entry in the autogenerated TOSCA schema.
+
+The `validators` option contains a set of declarative object validators applied to every object of the present model when it is saved. Validators are a comma separated
+list of tuples, where the two elements of each tuple are separated by a ':'. The first element of the tuple is a reference to an XOS policy (described in another section of this document). The second element is an error message that is returned to an API client that attempts an operation that does not pass validation.
+
+```protobuf
+option validators = "instance_creator:Instance has no creator, instance_isolation: Container instance {obj.name} must use container image, instance_isolation_container_vm_parent:Container-vm instance {obj.name} must have a parent";
+```
+
+The gui\_hidden option is a directive to the XOS GUI to exclude the present model from the default view provided to users.
+
+```protobuf
+option null = True
+```
### Field Options