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 <[email protected]> Authored: Mon May 19 19:48:45 2014 -0500 Committer: Alan M. Carroll <[email protected]> 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
