You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2023/06/21 00:00:20 UTC
[trafficserver] branch master updated: doc: fix the internal libraries section formatting (#9879)
This is an automated email from the ASF dual-hosted git repository.
jpeach 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 2a0dcd0c37 doc: fix the internal libraries section formatting (#9879)
2a0dcd0c37 is described below
commit 2a0dcd0c37835416ea58718b0814da93e0ed5c9f
Author: James Peach <jp...@apache.org>
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 <jp...@apache.org>
---
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