doc: enhance explanation

Merge pages
dipcoat-image · Oct 11, 2023 · 4c4e411 · 4c4e411
1 parent 891b057
commit 4c4e411
Show file tree

Hide file tree

Showing 4 changed files with 25 additions and 19 deletions.
diff --git a/doc/source/explanation/caching.rst → doc/source/explanation/design.rst b/doc/source/explanation/caching.rst → doc/source/explanation/design.rst
@@ -1,7 +1,15 @@
+Core class design
+=================
+
+.. _generic:
+
+Generic typing
+--------------
+
 .. _caching:
 
 Caching
-=======
+-------
 
 Caching of methods **MUST** be done in the instance itself, not in
 an external container.
@@ -15,3 +23,18 @@ soon crash.
 It is generally OK to use external caching in experiment class and analysis
 class, as they need relatively small memory space. Of course, this does not
 hold if your implementations require large memory space.
+
+__slots__
+---------
+
+Classes in DipcoatImage-FiniteDepth intentionally not define
+:obj:`~object.__slots__`.
+
+Slots are useful when large number of objects simultaneously exist,
+which is unlikely in our case where each object consumes large memory
+because of the image data it stores. Instead of constructing multiple
+objects, we need to handle small number of objects and destroy them
+as soon as possible. Hence, having slots does more harm than good.
+
+Verifying
+---------
diff --git a/doc/source/explanation/generic.rst b/doc/source/explanation/generic.rst
diff --git a/doc/source/explanation/index.rst b/doc/source/explanation/index.rst
@@ -9,7 +9,5 @@ Explanations
    install
    documentation
    testing
-   slots
-   caching
-   generic
+   design
    error-notes
diff --git a/doc/source/explanation/slots.rst b/doc/source/explanation/slots.rst