diff --git a/doc/rapi.rst b/doc/rapi.rst
index c80a30931069e6e61fd7d7b7a22164ca07e3232b..313364cae3b0890b687ea481dc3c9180efc5028a 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -166,6 +166,61 @@ likely to succeed or at least start executing.
 Force operation to continue even if it will cause the cluster to become
 inconsistent (e.g. because there are not enough master candidates).
 
+Parameter details
+-----------------
+
+Some parameters are not straight forward, so we describe them in details
+here.
+
+.. _rapi-ipolicy:
+
+``ipolicy``
++++++++++++
+
+The instance policy specification is a dict with the following fields:
+
+.. pyassert::
+
+  constants.IPOLICY_ALL_KEYS == set([constants.ISPECS_MIN,
+                                     constants.ISPECS_MAX,
+                                     constants.ISPECS_STD,
+                                     constants.IPOLICY_DTS,
+                                     constants.IPOLICY_VCPU_RATIO])
+
+
+.. pyassert::
+
+  (set(constants.ISPECS_PARAMETER_TYPES.keys()) ==
+   set([constants.ISPEC_MEM_SIZE,
+        constants.ISPEC_DISK_SIZE,
+        constants.ISPEC_DISK_COUNT,
+        constants.ISPEC_CPU_COUNT,
+        constants.ISPEC_NIC_COUNT]))
+
+.. |ispec-min| replace:: :pyeval:`constants.ISPECS_MIN`
+.. |ispec-max| replace:: :pyeval:`constants.ISPECS_MAX`
+.. |ispec-std| replace:: :pyeval:`constants.ISPECS_STD`
+
+
+|ispec-min|, |ispec-max|, |ispec-std|
+  A sub- `dict` with the following fields, which sets the limit and standard
+  values of the instances:
+
+  :pyeval:`constants.ISPEC_MEM_SIZE`
+    The size in MiB of the memory used
+  :pyeval:`constants.ISPEC_DISK_SIZE`
+    The size in MiB of the disk used
+  :pyeval:`constants.ISPEC_DISK_COUNT`
+    The numbers of disks used
+  :pyeval:`constants.ISPEC_CPU_COUNT`
+    The numbers of cpus used
+  :pyeval:`constants.ISPEC_NIC_COUNT`
+    The numbers of nics used
+:pyeval:`constants.IPOLICY_DTS`
+  A `list` of disk templates allowed for instances using this policy
+:pyeval:`constants.IPOLICY_VCPU_RATIO`
+  Maximum ratio of virtual to physical CPUs (`float`)
+
 Usage examples
 --------------
 
diff --git a/lib/opcodes.py b/lib/opcodes.py
index b928b8cdcf697b2a7fdda9b7fc2f13f75bf1754a..16cba8c7079e5c81f6fb23b57b3e4e9dab1b1d99 100644
--- a/lib/opcodes.py
+++ b/lib/opcodes.py
@@ -803,7 +803,8 @@ class OpClusterSetParams(OpCode):
      "Whether to wipe disks before allocating them to instances"),
     ("nicparams", None, ht.TMaybeDict, "Cluster-wide NIC parameter defaults"),
     ("ndparams", None, ht.TMaybeDict, "Cluster-wide node parameter defaults"),
-    ("ipolicy", None, ht.TMaybeDict, "Cluster-wide instance policy specs"),
+    ("ipolicy", None, ht.TMaybeDict,
+     "Cluster-wide :ref:`instance policy <rapi-ipolicy>` specs"),
     ("drbd_helper", None, ht.TOr(ht.TString, ht.TNone), "DRBD helper program"),
     ("default_iallocator", None, ht.TOr(ht.TString, ht.TNone),
      "Default iallocator for cluster"),
@@ -1438,7 +1439,8 @@ class OpGroupAdd(OpCode):
     _PDiskParams,
     _PHvState,
     _PDiskState,
-    ("ipolicy", None, ht.TMaybeDict, "Group-wide instance policy specs"),
+    ("ipolicy", None, ht.TMaybeDict,
+     "Group-wide :ref:`instance policy <rapi-ipolicy>` specs"),
     ]