This is an automated email from the ASF dual-hosted git repository.
zwoop pushed a commit to branch 9.2.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/9.2.x by this push:
new aae9552b7e doc: fix the internal libraries section formatting (#9879)
aae9552b7e is described below
commit aae9552b7e985db6c925675caa2382d2053a121e
Author: James Peach <[email protected]>
AuthorDate: Wed Jun 21 10:00:15 2023 +1000
doc: fix the internal libraries section formatting (#9879)
Use the standard Sphinx heading level conventions to mark content within
the internal libraries documentation as subsections. This makes the
sections nest correctly in the tables of contents, rather than being
hoisted up to the chapter level.
Signed-off-by: James Peach <[email protected]>
(cherry picked from commit 2a0dcd0c37835416ea58718b0814da93e0ed5c9f)
---
doc/developer-guide/internal-libraries/index.en.rst | 14 +++++++-------
.../internal-libraries/intrusive-hash-map.en.rst | 10 ++++------
.../internal-libraries/intrusive-list.en.rst | 6 +++---
doc/developer-guide/internal-libraries/scalar.en.rst | 8 ++++----
4 files changed, 18 insertions(+), 20 deletions(-)
diff --git a/doc/developer-guide/internal-libraries/index.en.rst
b/doc/developer-guide/internal-libraries/index.en.rst
index 81a7528713..32dfb332b6 100644
--- a/doc/developer-guide/internal-libraries/index.en.rst
+++ b/doc/developer-guide/internal-libraries/index.en.rst
@@ -28,13 +28,13 @@ development team.
.. toctree::
:maxdepth: 1
- TextView.en
+ AcidPtr.en
+ ArgParser.en
+ Extendible.en
+ MemArena.en
MemSpan.en
- scalar.en
+ TextView.en
buffer-writer.en
- intrusive-list.en
intrusive-hash-map.en
- MemArena.en
- AcidPtr.en
- Extendible.en
- ArgParser.en
+ intrusive-list.en
+ scalar.en
diff --git a/doc/developer-guide/internal-libraries/intrusive-hash-map.en.rst
b/doc/developer-guide/internal-libraries/intrusive-hash-map.en.rst
index 8b5fbe36f7..150e9a3594 100644
--- a/doc/developer-guide/internal-libraries/intrusive-hash-map.en.rst
+++ b/doc/developer-guide/internal-libraries/intrusive-hash-map.en.rst
@@ -33,17 +33,15 @@ In order to optimize lookup, the container can increase the
number of buckets us
be to be automatic or only done explicitly.
Usage
-*****
+=====
To use an :class:`IntrusiveHashMap` the element must provide support for the
container. This is done
through an associated descriptor class which provides the operations needed to
manipulate the elements
in the container.
-Examples
-========
Details
-*******
+=======
.. class:: template < typename H > IntrusiveHashMap
@@ -161,7 +159,7 @@ Details
modify them. In such cases this method provides a safe way to invoke
such mechanisms.
Design Notes
-************
+============
This is a refresh of an previously existing class, :code:`TSHahTable`. The
switch to C++ 11 and then
C++ 17 made it possible to do much better in terms of the internal
implementation and API. The
@@ -176,7 +174,7 @@ class can be removed. Elements with equal keys can be
handled in the same way as
containers, via iterator ranges, instead of a custom pseudo-iterator class.
Notes on :func:`IntrusiveHashMap::apply`
-========================================
+----------------------------------------
This was added after some experience with use of the container. Initially it
was added to make
cleaning up the container easier. Without it, cleanup looks like ::
diff --git a/doc/developer-guide/internal-libraries/intrusive-list.en.rst
b/doc/developer-guide/internal-libraries/intrusive-list.en.rst
index 2d49f44fa1..75ab3b1d01 100644
--- a/doc/developer-guide/internal-libraries/intrusive-list.en.rst
+++ b/doc/developer-guide/internal-libraries/intrusive-list.en.rst
@@ -28,7 +28,7 @@ iterators automatically convert to pointer as in normal use
of this class the co
will be referenced by pointers.
Definition
-**********
+==========
.. class:: template < typename L > IntrusiveDList
@@ -118,7 +118,7 @@ Definition
the end iterator is returned.
Usage
-*****
+=====
An instance of :class:`IntrusiveDList` acts as a container for items,
maintaining a doubly linked
list / queue of the objects and tracking the number of objects in the
container. There are methods
@@ -212,7 +212,7 @@ While this can be done directly with
:code:`reinterpret_cast<>`, use of :code:`t
typographic errors and warnings about type punning caused by
:code:`-fstrict-aliasing`.
Design Notes
-************
+============
The historic goal of this class is to replace the :code:`DLL` list support.
The benefits of this are
diff --git a/doc/developer-guide/internal-libraries/scalar.en.rst
b/doc/developer-guide/internal-libraries/scalar.en.rst
index 185fe06f3d..28b9c0056f 100644
--- a/doc/developer-guide/internal-libraries/scalar.en.rst
+++ b/doc/developer-guide/internal-libraries/scalar.en.rst
@@ -34,7 +34,7 @@ have the same memory footprint as the underlying integer
storage type. It is int
lengthy and error prone hand optimizations used to handle related values of
different scales.
Definition
-**********
+==========
TS.Scalar consists primarily of the template class :code:`Scalar`. Instances
of :class:`Scalar` hold
a *count* and represent a *value* which is the *count* multiplied by
:arg:`SCALE`. Note this
@@ -85,14 +85,14 @@ quantizes the values that can be represented by an instance.
Set the count to :arg:`c`.
Usage
-******
+======
In normal use a scalar evaluates to its value rather than its count. The goal
is to provide an
instance that appears to store unscaled values in a quantized way. The count
is accessible if
needed.
Assignment
-==========
+----------
Assigning values to, from, and between :class:`Scalar` instances is usually
straightforward with a few simple rules.
@@ -151,7 +151,7 @@ as possible.
a = round_down(2480); // a has count 24, value 2400.
Arithmetic
-==========
+----------
Arithmetic with scalars is based on the idea that a scalar represents its
value. This value retains the
scalar type for conversion checking but otherwise acts as the value. This
makes using scalar
