Some doc-strings

For #3

junos/default.nix

@@ -9,6 +9,10 @@ let
   mandatory.options = {
     supportPoE = mkOption {
       type = types.bool;
+      example = true;
+      description = ''
+        Wether this interface supports PoE.
+      '';
     };
   };
 in
@@ -23,8 +27,29 @@ in
     netconf.xmls.configuration = mkOption {
       type = types.str;
       readOnly = true;
+      description = ''
+        The full configuration to send to a JunOS.
+      '';
+    };
+    netconf.mandatoryInterfaces = mkOption {
+      type = types.attrsOf (types.submodule mandatory);
+      example = {
+        "ge-0/0/0" = {
+          supportPoE = true;
+        };
+        "ge-0/0/1" = {
+          supportPoE = true;
+        };
+        "xe-0/0/0" = {
+          supportPoE = false;
+        };
+      };
+      description = ''
+        JunOS require some interfaces to always be configured (even if they are disabled),
+        which correspond to physical interfaces of the switch. They have to be declared here
+        with some information about it (only if it supports PoE for now).
+      '';
     };
-    netconf.mandatoryInterfaces = mkOption { type = types.attrsOf (types.submodule mandatory); };
   };
   config.interfaces =
     let

junos/interfaces.nix

@@ -9,39 +9,53 @@ let
         { name, config, ... }:
         {
           options = {
-            enable = mkEnableOption "the logical interface ${intf-name}.${name}" // {
+            enable = mkEnableOption "this logical interface" // {
               default = true;
+              example = false;
             };
             family = {
               ethernet-switching = {
-                enable = mkEnableOption "the ethernet on the logical interface ${intf-name}.${name}";
+                enable = mkEnableOption "the ethernet switching on this logical interface";
                 interface-mode = mkOption {
-                  type = types.nullOr (
+                  type =
                     types.enum [
                       "trunk"
                       "access"
-                    ]
+                    ];
-                  );
+                  description = ''
-                  default = null;
+                    Mode of operation for vlan addressing of this interface.
+                    "trunk" means that the traffic is tagged, "access" means the
+                    traffic is tagged by the switch.
+                  '';
                 };
                 vlans = mkOption {
                   type = types.listOf (types.either types.str types.ints.unsigned);
                   default = [ ];
+                  description = ''
+                    Vlans that can be used on this interface.
+                    Only one ID should be here for "access" mode of operation.
+                  '';
                 };
               };
               #TODO : DHCP
               inet = {
-                enable = mkEnableOption "the IPv4 configuration of the logical interface ${intf-name}.${name}";
+                enable = mkEnableOption "the IPv4 configuration of this logical interface";
                 address = mkOption {
                   type = types.listOf types.str;
                   default = [ ];
+                  description = ''
+                    ipv4 addresses of this interface.
+                  '';
                 };
               };
               inet6 = {
-                enable = mkEnableOption "the IPv6 configuration of the logical interface ${intf-name}.${name}";
+                enable = mkEnableOption "the IPv6 configuration of this logical interface";
                 address = mkOption {
                   type = types.listOf types.str;
                   default = [ ];
+                  description = ''
+                    ipv6 addresses of this interface.
+                  '';
                 };
               };
             };
@@ -90,10 +104,13 @@ let
     in
     {
       options = {
-        enable = mkEnableOption "the physical interface ${intf-name}";
+        enable = mkEnableOption "this physical interface";
         unit = mkOption {
           type = types.attrsOf (types.submodule unit);
           default = { };
+          description = ''
+            Configuration of the logical interfaces on this physical interface.
+          '';
         };
         xml = mkOption {
           type = types.str;
@@ -116,7 +133,12 @@ let
 in
 {
   options = {
-    interfaces = mkOption { type = types.attrsOf (types.submodule interface); };
+    interfaces = mkOption {
+      type = types.attrsOf (types.submodule interface);
+      description = ''
+        The interfaces configuration.
+      '';
+    };
     netconf.xmls.interfaces = mkOption {
       type = types.str;
       visible = false;

junos/poe.nix

@@ -5,7 +5,7 @@ let
     { name, config, ... }:
     {
       options = {
-        enable = mkEnableOption "The PoE for interface ${name}.";
+        enable = mkEnableOption "the PoE for this interface";
         xml = mkOption {
           type = types.str;
           visible = false;
@@ -22,6 +22,9 @@ in
     poe.interfaces = mkOption {
       type = types.attrsOf (types.submodule interface-module);
       default = { };
+      description = ''
+        PoE configuration of interfaces.
+      '';
     };
     netconf.xmls.poe = mkOption {
       type = types.str;

junos/protocols.nix

@@ -2,7 +2,12 @@
 with lib;
 {
   options = {
-    protocols.rstp = mkOption { type = types.listOf types.str; };
+    protocols.rstp = mkOption {
+      type = types.listOf types.str;
+      description = ''
+        List of interfaces on which Rapid Spanning Tree Protocol should be enabled.
+      '';
+    };
     netconf.xmls.protocols = mkOption {
       type = types.str;
       visible = false;

junos/vlans.nix

@@ -8,6 +8,10 @@ let
         id = mkOption {
           type = types.nullOr types.ints.unsigned;
           default = null;
+          description = ''
+            The ID of this vlan, `null` means no ID.
+            Incompatible with vlans.${name}.id-list.
+          '';
         };
         id-list = mkOption {
           type =
@@ -17,8 +21,14 @@ let
                 {
                   config.__toString = _: "${toString config.begin}-${toString config.end}";
                   options = {
-                    begin = mkOption { type = types.ints.unsigned; };
+                    begin = mkOption {
-                    end = mkOption { type = types.ints.unsigned; };
+                      type = types.ints.unsigned;
+                      visible = false;
+                    };
+                    end = mkOption {
+                      type = types.ints.unsigned;
+                      visible = false;
+                    };
                     __toString = mkOption {
                       visible = false;
                       internal = true;
@@ -30,10 +40,24 @@ let
             in
             types.listOf (types.either types.ints.unsigned (types.submodule range_type));
           default = [ ];
+          example = [
+            42
+            { begin = 100; end = 200; }
+          ];
+          description = ''
+            List of IDs or IDs range to classify as this vlan.
+            Incompatible with vlans.${name}.id.
+          '';
         };
         l3-interface = mkOption {
           type = types.nullOr types.str;
           default = null;
+          example = "irb.0";
+          description = ''
+            Switch's logical interface to connect directly to this vlan.
+            This allows to communicate with the switch from a vlan without
+            having a cable looping back on it's management interface.
+          '';
         };
         xml = mkOption {
           type = types.str;
@@ -51,7 +75,7 @@ let
             !isNull config.l3-interface
           ) "<l3-interface>${config.l3-interface}</l3-interface>";
         in
-        ''
+        assert assertMsg (config.id == null || config.id-list == [ ]) "vlans.${name}.id and vlans.${name}.id-list are incompatible."; ''
           <vlan>
             <name>${name}</name>
             ${id}${id-list}${l3-intf}
@@ -61,7 +85,13 @@ let
 in
 {
   options = {
-    vlans = mkOption { type = types.attrsOf (types.submodule vlan); };
+    vlans = mkOption {
+      type = types.attrsOf (types.submodule vlan);
+      description = ''
+        Named vlans configuration. Allows to name vlans inside interface configuration,
+        instead of just using their IDs.
+      '';
+    };
     netconf.xmls.vlans = mkOption {
       type = types.str;
       visible = false;