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 2017/03/01 21:08:58 UTC
[trafficserver] branch master updated: Doc: Fixups. Doc build error
/ warning count is now ZERO. Keep it that way.
This is an automated email from the ASF dual-hosted git repository.
amc pushed a commit to branch master
in repository https://git-dual.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/master by this push:
new e9aac3e Doc: Fixups. Doc build error / warning count is now ZERO. Keep it that way.
e9aac3e is described below
commit e9aac3edf638fabd1e2f438cd70b7dd5eae38c2c
Author: Alan M. Carroll <am...@apache.org>
AuthorDate: Wed Mar 1 15:08:11 2017 -0600
Doc: Fixups. Doc build error / warning count is now ZERO.
Keep it that way.
---
doc/admin-guide/configuration/cache-basics.en.rst | 12 +--
doc/developer-guide/api/types/TSHttpHookID.en.rst | 66 +++++++++-------
doc/developer-guide/documentation/plugins.en.rst | 4 +
doc/developer-guide/documentation/ts-markup.en.rst | 16 +++-
.../plugins/http-headers/urls.en.rst | 91 ++++++++++++----------
doc/developer-guide/plugins/io/io-buffers.en.rst | 2 +-
6 files changed, 117 insertions(+), 74 deletions(-)
diff --git a/doc/admin-guide/configuration/cache-basics.en.rst b/doc/admin-guide/configuration/cache-basics.en.rst
index 7351d1e..d857fe9 100644
--- a/doc/admin-guide/configuration/cache-basics.en.rst
+++ b/doc/admin-guide/configuration/cache-basics.en.rst
@@ -708,13 +708,13 @@ any buffers associated with :ref:`transform plugins <developer-plugins-http-tran
Transaction buffering control can be enabled globally by using configuration
variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin.
-================= ================================================== ================================================
+================= ================================================== =======================================================
Value Variable :c:func:`TSHttpTxnConfigIntSet` key
-================= ================================================== ================================================
-Enable buffering :ts:cv:`proxy.config.http.flow_control.enabled` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`
-Set high water :ts:cv:`proxy.config.http.flow_control.high_water` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER`
-Set low water :ts:cv:`proxy.config.http.flow_control.low_water` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER`
-================= ================================================== ================================================
+================= ================================================== =======================================================
+Enable buffering :ts:cv:`proxy.config.http.flow_control.enabled` :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`
+Set high water :ts:cv:`proxy.config.http.flow_control.high_water` :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER_MARK`
+Set low water :ts:cv:`proxy.config.http.flow_control.low_water` :c:member:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER_MARK`
+================= ================================================== =======================================================
Be careful to always have the low water mark equal or less than the high water
mark. If you set only one, the other will be set to the same value.
diff --git a/doc/developer-guide/api/types/TSHttpHookID.en.rst b/doc/developer-guide/api/types/TSHttpHookID.en.rst
index 0520931..5d5a835 100644
--- a/doc/developer-guide/api/types/TSHttpHookID.en.rst
+++ b/doc/developer-guide/api/types/TSHttpHookID.en.rst
@@ -16,6 +16,8 @@
.. include:: ../../../common.defs
+.. default-domain:: c
+
TSHttpHookID
************
@@ -32,56 +34,68 @@ up :ref:`developer-plugins-continuations` callbacks.
Enumeration Members
===================
-.. c:member:: TSHttpHookID TS_HTTP_READ_REQUEST_HDR_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_READ_REQUEST_HDR_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_OS_DNS_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_OS_DNS_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_SEND_REQUEST_HDR_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_SEND_REQUEST_HDR_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_READ_CACHE_HDR_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_READ_CACHE_HDR_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_READ_RESPONSE_HDR_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_READ_RESPONSE_HDR_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_SEND_RESPONSE_HDR_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_SEND_RESPONSE_HDR_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_REQUEST_TRANSFORM_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_REQUEST_TRANSFORM_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_RESPONSE_TRANSFORM_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_RESPONSE_TRANSFORM_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_SELECT_ALT_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_SELECT_ALT_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_TXN_START_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_TXN_START_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_TXN_CLOSE_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_TXN_CLOSE_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_SSN_START_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_SSN_START_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_SSN_CLOSE_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_SSN_CLOSE_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_PRE_REMAP_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_PRE_REMAP_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_POST_REMAP_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_POST_REMAP_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_RESPONSE_CLIENT_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_RESPONSE_CLIENT_HOOK
-.. c:member:: TSHttpHookID TS_SSL_FIRST_HOOK
+.. c:macro:: TSHttpHookID TS_SSL_FIRST_HOOK
-.. c:member:: TSHttpHookID TS_VCONN_PRE_ACCEPT_HOOK
+.. c:macro:: TSHttpHookID TS_VCONN_PRE_ACCEPT_HOOK
-.. c:member:: TSHttpHookID TS_SSL_SNI_HOOK
+.. c:macro:: TSHttpHookID TS_SSL_SNI_HOOK
-.. c:member:: TSHttpHookID TS_SSL_CERT_HOOK
+.. c:macro:: TSHttpHookID TS_SSL_CERT_HOOK
-.. c:member:: TSHttpHookID TS_SSL_SERVERNAME_HOOK
+.. c:macro:: TSHttpHookID TS_SSL_SERVERNAME_HOOK
-.. c:member:: TSHttpHookID TS_SSL_LAST_HOOK
+.. c:macro:: TSHttpHookID TS_SSL_LAST_HOOK
-.. c:member:: TSHttpHookID TS_HTTP_LAST_HOOK
+.. c:macro:: TSHttpHookID TS_HTTP_LAST_HOOK
Description
===========
-Note that :member:`TS_SSL_CERT_HOOK` and :member:`TS_SSL_SNI_HOOK` hook the same openssl callbacks.
-In openssl 1.0.2 and beyond :member:`TS_SSL_SERVERNAME_HOOK` is involved only for the openssl servername callback. :member:`TS_SSL_SNI_HOOK` and :member:`TS_SSL_CERT_HOOK` are called for the openssl certificate callback.
+Note that :macro:`TS_SSL_CERT_HOOK` and :macro:`TS_SSL_SNI_HOOK` correspond to the same openssl
+callbacks. This is done for backwards compatibility. :macro:`TS_SSL_SNI_HOOK` is expected
+to be deprecated and removed, plugins using this should change to :macro:`TS_SSL_CERT_HOOK` or
+:macro:`TS_SSL_SERVERNAME_HOOK` as appropriate.
+
+.. warning:: openssl 1.0.2 and later versions
+
+ :macro:`TS_SSL_SERVERNAME_HOOK` is invoked for the openssl servername callback.
+ :macro:`TS_SSL_SNI_HOOK` and :macro:`TS_SSL_CERT_HOOK` are invoked for the openssl certificate
+ callback which is not guaranteed to be invoked for a TLS transaction.
+
+ This is a behavior change dependent on the version of openssl. To avoid problems use
+ :macro:`TS_SSL_SERVERNAME_HOOK` to get called back for all TLS transaction and
+ :macro:`TS_SSL_CERT_HOOK` to get called back only to select a certificate.
diff --git a/doc/developer-guide/documentation/plugins.en.rst b/doc/developer-guide/documentation/plugins.en.rst
index 7abbd2d..4257a11 100644
--- a/doc/developer-guide/documentation/plugins.en.rst
+++ b/doc/developer-guide/documentation/plugins.en.rst
@@ -150,3 +150,7 @@ features of the documentation which may be relevant for your plugin. Developers
are very strongly encouraged to use this template whenever possible, as a means
of producing and maintaining a consistent format for plugin documentation.
+
+.. _developer-doc-plugin-template:
+
+.. note:: *to be done*
diff --git a/doc/developer-guide/documentation/ts-markup.en.rst b/doc/developer-guide/documentation/ts-markup.en.rst
index 32642da..1f8b372 100644
--- a/doc/developer-guide/documentation/ts-markup.en.rst
+++ b/doc/developer-guide/documentation/ts-markup.en.rst
@@ -54,6 +54,8 @@ three required arguments (the scope, which is the literal string
argument (the default value). ::
:ts:cv: <scope> <variable name> <data type> <value>
+
+This corresponds exactly to the line in :file:`records.config`.
Definition
~~~~~~~~~~
@@ -90,8 +92,18 @@ Value
Options
~~~~~~~
-The domain for configuration variables takes only a single option at this time.
-
+The domain for configuration variables takes serveral options.
+
+reloadable
+ If marked the effect of the variable can be changed by reloading the |TS| configuration.
+
+overridable
+ A flag option that should be set if the variable is overridable per transaction.
+
+units
+ This takes a string option which is a description of the units for the variable. The most common
+ case is to distinguish time values with units such as "seconds", "minutes", "milliseconds", etc.
+
deprecated
A simple flag option which, when attached to a configuration variable, is
used to indicate that the variable has been deprecated and should no longer
diff --git a/doc/developer-guide/plugins/http-headers/urls.en.rst b/doc/developer-guide/plugins/http-headers/urls.en.rst
index 2aea573..7c90a77 100644
--- a/doc/developer-guide/plugins/http-headers/urls.en.rst
+++ b/doc/developer-guide/plugins/http-headers/urls.en.rst
@@ -49,57 +49,70 @@ instance, the function that retrieves the host portion of a URL is named
To facilitate fast comparisons and reduce storage size, Traffic Server
defines several preallocated scheme names.
-``TS_URL_SCHEME_FILE``
- "file"
- ``TS_URL_LEN_FILE``
+.. c:var:: TS_URL_SCHEME_FILE
+ "file"
-``TS_URL_SCHEME_FTP``
- "ftp"
- ``TS_URL_LEN_FTP``
+.. c:var:: TS_URL_LEN_FILE
-``TS_URL_SCHEME_GOPHER``
- "gopher"
- ``TS_URL_LEN_GOPHER``
+.. c:var:: TS_URL_SCHEME_FTP
+ "ftp"
-``TS_URL_SCHEME_HTTP``
- "http"
- ``TS_URL_LEN_HTTP``
+.. c:var:: TS_URL_LEN_FTP
-``TS_URL_SCHEME_HTTPS``
- "https"
- ``TS_URL_LEN_HTTPS``
+.. c:var:: TS_URL_SCHEME_GOPHER
+ "gopher"
-``TS_URL_SCHEME_MAILTO``
- "mailto"
- ``TS_URL_LEN_MAILTO``
+.. c:var:: TS_URL_LEN_GOPHER
-``TS_URL_SCHEME_NEWS``
- "news"
- ``TS_URL_LEN_NEWS``
+.. c:var:: TS_URL_SCHEME_HTTP
+ "http"
-``TS_URL_SCHEME_NNTP``
- "nntp"
- ``TS_URL_LEN_NNTP``
+.. c:var:: TS_URL_LEN_HTTP
-``TS_URL_SCHEME_PROSPERO``
- "prospero"
- ``TS_URL_LEN_PROSPERO``
+.. c:var:: TS_URL_SCHEME_HTTPS
+ "https"
-``TS_URL_SCHEME_TELNET``
- "telnet"
- ``TS_URL_LEN_TELNET``
+.. c:var:: TS_URL_LEN_HTTPS
-``TS_URL_SCHEME_WAIS``
- "wais"
- ``TS_URL_LEN_WAIS``
+.. c:var:: TS_URL_SCHEME_MAILTO
+ "mailto"
-``TS_URL_SCHEME_WS``
- "ws"
- ``TS_URL_LEN_WS``
+.. c:var:: TS_URL_LEN_MAILTO
-``TS_URL_SCHEME_WSS``
- "wss"
- ``TS_URL_LEN_WSS``
+.. c:var:: TS_URL_SCHEME_NEWS
+ "news"
+
+.. c:var:: TS_URL_LEN_NEWS
+
+.. c:var:: TS_URL_SCHEME_NNTP
+ "nntp"
+
+.. c:var:: TS_URL_LEN_NNTP
+
+.. c:var:: TS_URL_SCHEME_PROSPERO
+ "prospero"
+
+.. c:var:: TS_URL_LEN_PROSPERO
+
+.. c:var:: TS_URL_SCHEME_TELNET
+ "telnet"
+
+.. c:var:: TS_URL_LEN_TELNET
+
+.. c:var:: TS_URL_SCHEME_WAIS
+ "wais"
+
+.. c:var:: TS_URL_LEN_WAIS
+
+.. c:var:: TS_URL_SCHEME_WS
+ "ws"
+
+.. c:var:: TS_URL_LEN_WS
+
+.. c:var:: TS_URL_SCHEME_WSS
+ "wss"
+
+.. c:var:: TS_URL_LEN_WSS
The scheme names above are defined in ``ts.h`` as ``const`` ``char*``
strings. When Traffic Server sets the scheme portion of the URL (or any
diff --git a/doc/developer-guide/plugins/io/io-buffers.en.rst b/doc/developer-guide/plugins/io/io-buffers.en.rst
index 73c49ac..58263f4 100644
--- a/doc/developer-guide/plugins/io/io-buffers.en.rst
+++ b/doc/developer-guide/plugins/io/io-buffers.en.rst
@@ -51,6 +51,6 @@ Additional information about IO buffer functions:
- Bytes that have already been read may not necessarily be freed within
the ``TSIOBuffer``. To consume bytes that have been read, you must
- call :c:func:`TSIOBufferConsume`.
+ call :c:func:`TSIOBufferReaderConsume`.
--
To stop receiving notification emails like this one, please contact
['"commits@trafficserver.apache.org" <co...@trafficserver.apache.org>'].