trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject [trafficserver] branch master updated: Doc: Fix more documentation build warnings.
Date Wed, 21 Feb 2018 21:35:38 GMT
This is an automated email from the ASF dual-hosted git repository.

amc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficserver.git


The following commit(s) were added to refs/heads/master by this push:
     new 4f9bad5  Doc: Fix more documentation build warnings.
4f9bad5 is described below

commit 4f9bad54d3716db32dd9bf58372c96918455caf7
Author: Alan M. Carroll <amc@apache.org>
AuthorDate: Tue Feb 20 15:16:45 2018 -0600

    Doc: Fix more documentation build warnings.
---
 doc/developer-guide/api/types/CoreTypes.en.rst     |  2 --
 doc/developer-guide/api/types/TSEvent.en.rst       | 23 ++++++++++++
 .../cache-architecture/core-cache-functions.en.rst | 16 ---------
 .../cache-architecture/data-structures.en.rst      | 41 ++++++++++++----------
 .../internal-libraries/memview.en.rst              |  2 ++
 .../internal-libraries/scalar.en.rst               | 34 +++++++++++-------
 .../internal-libraries/string_view.en.rst          | 12 ++++---
 doc/developer-guide/threads-and-events.en.rst      |  2 +-
 8 files changed, 78 insertions(+), 54 deletions(-)

diff --git a/doc/developer-guide/api/types/CoreTypes.en.rst b/doc/developer-guide/api/types/CoreTypes.en.rst
index 0840bca..9badf57 100644
--- a/doc/developer-guide/api/types/CoreTypes.en.rst
+++ b/doc/developer-guide/api/types/CoreTypes.en.rst
@@ -33,6 +33,4 @@ Description
 
 These types are provided by the compiler ("built-in") or from a required operating system,
POSIX, or package header.
 
-
-
 .. cpp:type:: uint24_t
diff --git a/doc/developer-guide/api/types/TSEvent.en.rst b/doc/developer-guide/api/types/TSEvent.en.rst
index 0de62c7..e4abf84 100644
--- a/doc/developer-guide/api/types/TSEvent.en.rst
+++ b/doc/developer-guide/api/types/TSEvent.en.rst
@@ -189,3 +189,26 @@ Enumeration Members
 
 Description
 ===========
+
+These are the event types used to drive continuations in the event system.
+
+.. c:type:: EventType
+
+   The basic category of an event.
+
+.. c:macro:: EVENT_NONE
+
+   A non-specific event.
+
+.. c:macro:: EVENT_IMMEDIATE
+
+   A direct event that is not based on an external event.
+
+.. c:macro:: EVENT_INTERVAL
+
+   An event generated by a time based event.
+
+.. cpp:var:: EventType EVENT_IMMEDIATE
+
+   See :c:macro:`EVENT_IMMEDIATE`.
+
diff --git a/doc/developer-guide/cache-architecture/core-cache-functions.en.rst b/doc/developer-guide/cache-architecture/core-cache-functions.en.rst
index 66ec9b2..762416b 100644
--- a/doc/developer-guide/cache-architecture/core-cache-functions.en.rst
+++ b/doc/developer-guide/cache-architecture/core-cache-functions.en.rst
@@ -40,22 +40,6 @@ Core Cache Types
 
    A range of content to be evacuated.
 
-.. cpp:class:: Vol
-
-   A representation of a :term:`cache stripe`.
-
-   .. cpp:member:: off_t data_blocks
-
-      The number of blocks of storage in the stripe.
-
-   .. cpp:member:: DLL<EvacuationBlock> evacuate
-
-      A list of blocks to evacuate.
-
-   .. cpp:member:: int aggWrite(int event, void * e)
-
-      Schedule the aggregation buffer to be written to disk.
-      
 .. cpp:class:: CacheProcessor
 
    The singleton cache management object. This handles threads and global initialization
for the cache.
diff --git a/doc/developer-guide/cache-architecture/data-structures.en.rst b/doc/developer-guide/cache-architecture/data-structures.en.rst
index 5b87e36..73c6a37 100644
--- a/doc/developer-guide/cache-architecture/data-structures.en.rst
+++ b/doc/developer-guide/cache-architecture/data-structures.en.rst
@@ -85,28 +85,32 @@ Data Structures
 
    * Timestamps for request and response from :term:`origin server`.
 
-.. class:: EvacuationBlock
-
-    Record for evacuation.
-
 .. class:: Vol
 
    This represents a :term:`storage unit` inside a :term:`cache volume`.
 
-   .. member:: off_t Vol::segments
+   .. cpp:member:: off_t data_blocks
+
+      The number of blocks of storage in the stripe.
+
+   .. cpp:member:: int aggWrite(int event, void * e)
+
+      Schedule the aggregation buffer to be written to disk.
+      
+   .. member:: off_t segments
 
       The number of segments in the volume. This will be roughly the total
       number of entries divided by the number of entries in a segment. It will
       be rounded up to cover all entries.
 
-   .. member:: off_t Vol::buckets
+   .. member:: off_t buckets
 
       The number of buckets in the volume. This will be roughly the number of
       entries in a segment divided by ``DIR_DEPTH``. For currently defined
       values this is around 16,384 (2^16 / 4). Buckets are used as the targets
       of the index hash.
 
-   .. member:: DLL\<EvacuationBlock\> Vol::evacuate
+   .. member:: DLL<EvacuationBlock> evacuate
 
       Array of of :class:`EvacuationBlock` buckets. This is sized so there
       is one bucket for every evacuation span.
@@ -121,49 +125,48 @@ Data Structures
          from :arg:`low` to :arg:`high`. Return ``0`` if no evacuation was started,
          non-zero otherwise.
 
-
 .. class:: Doc
 
    Defined in :ts:git:`iocore/cache/P_CacheVol.h`.
 
-   .. member:: uint32_t Doc::magic
+   .. member:: uint32_t magic
 
       Validity check value. Set to ``DOC_MAGIC`` for a valid document.
 
-   .. member:: uint32_t Doc::len
+   .. member:: uint32_t len
 
       The length of this segment including the header length, fragment table,
       and this structure.
 
-   .. member:: uint64_t Doc::total_len
+   .. member:: uint64_t total_len
 
       Total length of the entire document not including meta data but including
       headers.
 
-   .. member:: INK_MD5 Doc::first_key
+   .. member:: INK_MD5 first_key
 
       First index key in the document (the index key used to locate this object
       in the volume index).
 
-   .. member:: INK_MD5 Doc::key
+   .. member:: INK_MD5 key
 
       The index key for this fragment. Fragment keys are computationally
       chained so that the key for the next and previous fragments can be
       computed from this key.
 
-   .. member:: uint32_t Doc::hlen
+   .. member:: uint32_t hlen
 
       Document header (metadata) length. This is not the length of the HTTP
       headers.
 
-   .. member:: uint8_t Doc::ftype
+   .. member:: uint8_t ftype
 
       Fragment type. Currently only ``CACHE_FRAG_TYPE_HTTP`` is used. Other
       types may be used for cache extensions if those are ever implemented.
 
-   .. member:: uint24_t Doc::flen
+   .. member:: uint24_t flen
 
-      Fragment table length, if any. Only the first ``Doc`` in an object should
+      Fragment table length, if any. Only the first :class:`Doc` in an object should
       contain a fragment table.
 
       The fragment table is a list of offsets relative to the HTTP content (not
@@ -177,11 +180,11 @@ Data Structures
 
       Removed as of version 3.3.0. [#fragment-offset-table]_
 
-   .. member:: uint32_t Doc::sync_serial
+   .. member:: uint32_t sync_serial
 
       Unknown.
 
-   .. member:: uint32_t Doc::write_serial
+   .. member:: uint32_t write_serial
 
       Unknown.
 
diff --git a/doc/developer-guide/internal-libraries/memview.en.rst b/doc/developer-guide/internal-libraries/memview.en.rst
index e1524e0..75f57f8 100644
--- a/doc/developer-guide/internal-libraries/memview.en.rst
+++ b/doc/developer-guide/internal-libraries/memview.en.rst
@@ -31,6 +31,8 @@ Synopsis
 
 .. class:: StringView
 
+.. class:: TextView
+
 These classes act as views in to already allocated memory. Internally in |TS| work must be
done with
 string or memory entities that are embedded in larger pre-existing memory structures. These
classes
 are designed to make that easier, more efficient, and less error prone.
diff --git a/doc/developer-guide/internal-libraries/scalar.en.rst b/doc/developer-guide/internal-libraries/scalar.en.rst
index 73dd69b..087c13c 100644
--- a/doc/developer-guide/internal-libraries/scalar.en.rst
+++ b/doc/developer-guide/internal-libraries/scalar.en.rst
@@ -40,27 +40,37 @@ TS.Scalar consists primarily of the template class :code:`Scalar`. Instances
of
 a *count* and represent a *value* which is the *count* multiplied by :arg:`SCALE`. Note this
 quantizes the values that can be represented by an instance.
 
-.. class:: template < intmax_t SCALE, typename COUNTER, typename TAG > Scalar
+.. class:: template < intmax_t SCALE, typename C, typename TAG > Scalar
 
-   .. var:: intmax_t SCALE
+   A quantized integral with a distinct type.
 
-      The scaling factor for the type. This must be an positive integer. Values for an instance
will
-      always be an integral multiple of :arg:`SCALE`.
+   :tparam SCALE: Scaling factor.
+   :tparam C: Base storage type.
+   :tparam TAG: Distinguishing type tag.
 
    .. type:: COUNTER
 
-      This is the type used to hold the internal count. This must be an integral type. It
can be omitted and will default to :code:`int`. The size of an instance is the same size as
:arg:`COUNTER`.
+      Imported template parameter :arg:`C`.
 
-   .. type:: TAG
+   The scaling factor :arg:`SCALE` must be an positive integer. Values for an instance will
always
+   be an integral multiple of :arg:`SCALE`. The alue of an instance will always be a
+   multiple of :arg:`SCALE`.
 
-      A distinguishing tag which must be a type. It can be omitted and will default to :code:`tag::generic`.
This means that :class:`Scalar` types without a tag will all interoperate. The tag type is
usually a :code:`struct` defined in name only. ::
+   :arg:`C` must be an integral type. An instance of this type is used to hold the internal
+   count.It can be omitted and will default to :code:`int`. The size of an instance is the
same size
+   as :arg:`C` and an instance of that type can be replaced with a :class:`Scalar` of that
size
+   without changing the memory layout.
 
-         struct YoureIt; // no other information about YoureIt is required.
-         typedef Scalar<100, int, YoureIt> HectoTouch; // how many hundreds of touches.
+   :arg:`TAG` must be a type. It can be omitted and will default to :code:`tag::generic`.
:arg:`TAG`
+   is a mechanism for preventing accidental cross assignments. Assignment of any sort from
a
+   :class:`Scalar` instance to another instance with a different :arg:`TAG` is a compile
time error.
+   If this isn't useful :arg:`TAG` can be omitted and will default to :code:`tag::generic`
which
+   will enable all instances to interoperate.
 
-      :arg:`TAG` s a mechanism for preventing accidental cross assignments. Assignment of
any sort from
-      a :class:`Scalar` to another with a different :arg:`TAG` is a compile time error. If
this isn't
-      useful the :arg:`TAG` can be omitted and will default to the same for all derived types.
+   The type used for :arg:`TAG` can be defined in name only.::
+
+      struct YoureIt; // no other information about YoureIt is required.
+      typedef Scalar<100, int, YoureIt> HectoTouch; // how many hundreds of touches.
 
    .. function:: COUNTER count() const
 
diff --git a/doc/developer-guide/internal-libraries/string_view.en.rst b/doc/developer-guide/internal-libraries/string_view.en.rst
index 911dd23..4d67f3e 100644
--- a/doc/developer-guide/internal-libraries/string_view.en.rst
+++ b/doc/developer-guide/internal-libraries/string_view.en.rst
@@ -29,10 +29,10 @@ Synopsis
 
 .. class:: string_view
 
-This is an internal implementation of `std::string_view
-<https://en.cppreference.com/w/cpp/header/string_view>`__. This was done because
-:code:`std::string_view` is part of the C++17 standard and therefore cannot be assumed in
our
-supported compilers (which are currently only C++11).
+   An internal implementation of `std::string_view
+   <https://en.cppreference.com/w/cpp/header/string_view>`__. This was done because
+   :code:`std::string_view` is part of the C++17 standard and therefore cannot be assumed
in our
+   supported compilers (which are currently only C++11).
 
 Description
 ===========
@@ -60,6 +60,10 @@ If you discover any other differences, that is a bug in our implementation
and s
 For a class that provides a much richer set of text manipulation methods, see :class:`TextView`
 which is a subclass of :class:`string_view`.
 
+For passing instance of :class:`string_view` it is reasonable to pass it by value. Examining
machine
+code shows this is the same cost as passing the pointer and length as two arguments and saves
+indirection on in the called code.
+
 There is no shortage of additional reference material available, beyond the basic description
noted
 above, which serves to describe the API and usage of this class, and duplicating it here
would serve
 no purpose.
diff --git a/doc/developer-guide/threads-and-events.en.rst b/doc/developer-guide/threads-and-events.en.rst
index 076ae18..6f3cbb0 100644
--- a/doc/developer-guide/threads-and-events.en.rst
+++ b/doc/developer-guide/threads-and-events.en.rst
@@ -191,7 +191,7 @@ Types
 
       Register an event type with the name :arg:`name`. The unique type index is returned.
 
-   .. function:: Event * schedule_spawn(Continuation * c, EventType ev_type, int event =
EVENT_IMMEDIATE, void * cookie = NULL)
+   .. function:: Event * schedule_spawn(Continuation * c, EventType ev_type, int event =
EVENT_IMMEDIATE, void * cookie = nullptr)
 
       When the :class:`EventProcessor` starts a thread of type :arg:`ev_type`, :arg:`c` will
be
       called before any events are dispatched by the thread. The handler for :arg:`c` will
be called

-- 
To stop receiving notification emails like this one, please contact
amc@apache.org.

Mime
View raw message