You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2014/05/20 02:55:10 UTC
git commit: Doc: improvements to config variable implementation write
up.
Repository: trafficserver
Updated Branches:
refs/heads/master ce8304309 -> 51dffeb61
Doc: improvements to config variable implementation write up.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/51dffeb6
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/51dffeb6
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/51dffeb6
Branch: refs/heads/master
Commit: 51dffeb61ee4f620cafd7b37fb5e31cc951cd3f8
Parents: ce83043
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Mon May 19 19:48:45 2014 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Mon May 19 19:54:47 2014 -0500
----------------------------------------------------------------------
doc/arch/hacking/config-var-impl.en.rst | 37 ++++++++++++++++++++
.../configuration/records.config.en.rst | 2 +-
2 files changed, 38 insertions(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/51dffeb6/doc/arch/hacking/config-var-impl.en.rst
----------------------------------------------------------------------
diff --git a/doc/arch/hacking/config-var-impl.en.rst b/doc/arch/hacking/config-var-impl.en.rst
index 5f2df2d..722e358 100644
--- a/doc/arch/hacking/config-var-impl.en.rst
+++ b/doc/arch/hacking/config-var-impl.en.rst
@@ -165,6 +165,43 @@ is handled in a generic way, as described in the next section, or in a :ref:`mor
needed if the variable is marked as dynamically updateable (|RECU_DYNAMIC|_) although HTTP configuration variables
should be dynamic if possible.
+--------------------------
+Documentation and Defaults
+--------------------------
+
+A configuration variable should be documented in :file:`records.config`. There are many examples in the file already that can be used for guidance. The general format is to use the tag ::
+
+ .. ts:cv::
+
+The arguments to this are the same as for the configuration file. The documentation generator will pick out key bits and use them to decorate the entry. In particular if a value is present it will be removed and used as the default value. You can attach some additional options to the variable. These are
+
+reloadable
+ The variable can be reloaded via command line on a running Traffic Server.
+
+metric
+ Specify the units for the value. This is critical for variables that use unexpected or non-obvious metrics, such as minutes instead of seconds, or disk sectors instead of bytes.
+
+deprecated
+ Mark a variable as deprecated.
+
+.. topic:: Example
+
+ ::
+
+ :reloadable:
+ :metric: minutes
+ :deprecated:
+
+If you need to refer to another configuration variable in the documentation, you can use the form ::
+
+ :ts:cv:`the.full.name.of.the.variable`
+
+This will display the name as a link to the definition.
+
+In general a new configuration variable should be present in the default :file:`records.config`. Although users should peruse this documentation that is not as frequent an occurence as we would like. It is much more common to read through :file:`records.config` for values that can be tuned.
+
+Such defaults should be added to the file ``proxy/config/records.config.default.in``. This is used to generate the default :file:`records.config`. Just add the variable to the file in an appropriate place with a proper default as this will now override whatever default you put in the code for new installs.
+
------------------------------
Handling Updates
------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/51dffeb6/doc/reference/configuration/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst
index cef38fe..53c6973 100644
--- a/doc/reference/configuration/records.config.en.rst
+++ b/doc/reference/configuration/records.config.en.rst
@@ -420,7 +420,7 @@ Alarm Configuration
- the alarm message
- the value of :ts:cv:`proxy.config.product_name`
- - the value of :ts:cv:`proxy.config.admin.admin_user`
+ - the value of :ts:cv:`proxy.config.admin.user_id`
- the value of :ts:cv:`proxy.config.alarm_email`
.. ts:cv:: CONFIG proxy.config.alarm.abs_path STRING NULL