From 35129313151bda72cf972ad2bcc960a1b080b921 Mon Sep 17 00:00:00 2001 From: James Peach Date: Mon, 19 Jun 2023 12:11:46 +1000 Subject: [PATCH] doc: fix the internal libraries section formatting 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 --- .../internal-libraries/index.en.rst | 14 +++++++------- .../internal-libraries/intrusive-hash-map.en.rst | 10 ++++------ .../internal-libraries/intrusive-list.en.rst | 6 +++--- .../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 81a75287135..32dfb332b68 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 8b5fbe36f7c..150e9a35942 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 2d49f44fa1a..75ab3b1d013 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 185fe06f3d6..28b9c0056f3 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