doc: make admonitions collapsible

yvt · yvt · commit 90f970e0ba10 · 2020-11-02T22:44:20.000+09:00
diff --git a/src/r3/src/common.md b/src/r3/src/common.md
@@ -30,10 +30,23 @@
  *
  * # Usage
  *
+ * ## Normal
+ *
  *     <div class="admonition-follows"></div>
  *
  *     > **Title:** lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum
  *     > lorem ipsum
+ *
+ * ## Collapsible
+ *
+ *     <div class="admonition-follows"></div>
+ *
+ *     > <details>
+ *     > <summary>Title</summary>
+ *     >
+ *     > lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum
+ *     >
+ *     > </details>
  */
 .admonition-follows + blockquote {
     background: rgba(128, 128, 128, 0.1) !important;
@@ -44,6 +57,20 @@
     content: ""; display: block; margin-top: 1em;
 }
 
+.admonition-follows + blockquote summary {
+    cursor: pointer;
+    will-change: opacity;
+    user-select: none;
+    -webkit-user-select: none;
+    font-weight: bold;
+}
+.admonition-follows + blockquote summary:not([open]):not(:hover) {
+    opacity: 0.5;
+}
+.admonition-follows + blockquote summary + * {
+    margin-top: 1em;
+}
+
 /* Display a warning if some Cargo features are disabled. */
 .disabled-feature-warning > p > span:before { content: "Warning:"; font-weight: bold; }
 .disabled-feature-warning > p > span:after { content: " This documentation was built without a "; }
@@ -87,7 +114,7 @@ body.theme-ayu span.center img, body.theme-ayu center img {
 <script type="application/javascript">
 <!--
 // Monitors the current rustdoc theme and adds `.theme-NAME` to `<body>`
-(function () {
+function initThemeMonitor() {
     if (typeof getCurrentValue !== 'function' ||
         typeof switchTheme !== 'function' ||
         typeof getSystemValue !== 'function' ||
@@ -114,6 +141,12 @@ body.theme-ayu span.center img, body.theme-ayu center img {
         onApplyTheme(newTheme);
         originalSwitchTheme.apply(this, arguments);
     };
-})();
+}
+
+if (document.readyState === 'interactive' || document.readyState === 'complete') {
+    initThemeMonitor();
+} else {
+    document.addEventListener('DOMContentLoaded', initThemeMonitor);
+}
 -->
 </script>
diff --git a/src/r3/src/kernel/mutex.rs b/src/r3/src/kernel/mutex.rs
@@ -122,8 +122,11 @@ pub enum MutexProtocol {
 ///
 /// <div class="admonition-follows"></div>
 ///
-/// > **Relation to Other Specifications:** This behavior is based on robust
-/// > mutexes from POSIX.1-2008 (`PTHREAD_MUTEX_ROBUST`) with one difference:
+/// > <details>
+/// > <summary>Relation to Other Specifications</summary>
+/// >
+/// > This behavior is based on robust mutexes from POSIX.1-2008
+/// > (`PTHREAD_MUTEX_ROBUST`) with one difference:
 /// > A mutex never falls into an irrecoverable state — [`Mutex::lock`] would
 /// > repeatedly return `Err(Abandoned)` until [`Mutex::mark_consistent`] is
 /// > called. This change reduces the internal state bits and the complexity of
@@ -141,12 +144,17 @@ pub enum MutexProtocol {
 /// > All of the other operating systems' behavior described above can be
 /// > emulated by having a per-mutex flag and performing additional tasks in the
 /// > API translation layer.
+/// >
+/// > </details>
 ///
 /// [Win32 mutex]: https://docs.microsoft.com/en-us/windows/win32/sync/mutex-objects
 ///
 /// <div class="admonition-follows"></div>
 ///
-/// > **Rationale:** Every customization option brings an additional overhead.
+/// > <details>
+/// > <summary>Rationale</summary>
+/// >
+/// > Every customization option brings an additional overhead.
 /// > The overhead introduced by the robustness is likely to outweigh the
 /// > overhead to provide choices. Therefore, we decided not to add an attribute
 /// > to control the robustness.
@@ -162,6 +170,8 @@ pub enum MutexProtocol {
 /// > accessed again. To ensure this recommendation is followed correctly
 /// > (unless explicitly opted out), we decided to make the robustness the
 /// > default behavior.
+/// >
+/// > </details>
 ///
 /// # Locking Protocols
 ///
@@ -177,7 +187,9 @@ pub enum MutexProtocol {
 ///
 /// <div class="admonition-follows"></div>
 ///
-/// > **Relation to Other Specifications:**
+/// > <details>
+/// > <summary>Relation to Other Specifications</summary>
+/// >
 /// > POSIX supports specifying a locking protocol by
 /// > `pthread_mutexattr_setprotocol`. The following protocols are supported:
 /// > `PTHREAD_PRIO_NONE` (none), `PTHREAD_PRIO_INHERIT`
@@ -228,12 +240,16 @@ pub enum MutexProtocol {
 /// >  - The **Lower Priority** column indicates whether an owning task's
 /// >    priority may be lowered whenever it unlocks a mutex or only when it
 /// >    unlocks the last mutex held.
+/// >
+/// > </details>
 ///
 /// [the priority inheritance protocol]: https://en.wikipedia.org/wiki/Priority_inheritance
 ///
 /// <div class="admonition-follows"></div>
 ///
-/// > **Rationale:**
+/// > <details>
+/// > <summary>Rationale</summary>
+/// >
 /// > There are numerous reasons that led to the decision not to implement the
 /// > priority inheritance protocol.
 /// >
@@ -278,6 +294,8 @@ pub enum MutexProtocol {
 /// >
 /// > We decided to restrict the unlocking order to a lock-reverse order to
 /// > minimize the cost of maintaining the list of mutexes held by a task.
+/// >
+/// > </details>
 ///
 #[doc(include = "../common.md")]
 #[repr(transparent)]
diff --git a/src/r3/src/lib.md b/src/r3/src/lib.md
@@ -261,7 +261,7 @@ Like a lock guard of a mutex, CPU Lock can be thought of as something to be “o
 
 <div class="admonition-follows"></div>
 
-> **Relation to Other Specifications:** Inspired from [the μITRON4.0 specification](http://www.ertl.jp/ITRON/SPEC/mitron4-e.html). CPU Lock and Priority Boost correspond to a CPU locked state and a dispatching state from μITRON4.0, respectively. In contrast to this specification, both concepts are denoted by proper nouns in the R3 RTOS. This means phrases like “when the CPU is locked” are not allowed.
+> **Relation to Other Specifications:** Inspired from the μITRON4.0 specification. CPU Lock and Priority Boost correspond to a CPU locked state and a dispatching state from μITRON4.0, respectively. In contrast to this specification, both concepts are denoted by proper nouns in the R3 RTOS. This means phrases like “when the CPU is locked” are not allowed.
 >
 > CPU Lock corresponds to `SuspendOSInterrupts` and `ResumeOSInterrupts` from the OSEK/VDX specification.
 
@@ -294,7 +294,7 @@ A **task** ([`Task`]) is the kernel object that can create a thread whose execut
 
 <div class="admonition-follows"></div>
 
-> **Relation to Other Specifications:** Not many kernel designs use the word “thread” to describe the concept that applies to both of interrupts and tasks (one notable exception being [TI-RTOS]), most likely because threads are used to refer to a specific concept in general-purpose operating systems, or they are simply considered synonymous with tasks. For example, the closest concept in [the μITRON4.0 specification](http://www.ertl.jp/ITRON/SPEC/mitron4-e.html) is *processing units*. Despite that, it was decided that “thread” was an appropriate term to refer to this concept. The primary factors that drove this decision include: (1) the need for a conceptual entity that can “own” locks, and (2) that this concept is important for discussing thread safety without substituting every mention of “thread” with “task or interrupt handler”.
+> **Relation to Other Specifications:** Not many kernel designs use the word “thread” to describe the concept that applies to both of interrupts and tasks (one notable exception being [TI-RTOS]), most likely because threads are used to refer to a specific concept in general-purpose operating systems, or they are simply considered synonymous with tasks. For example, the closest concept in the μITRON4.0 specification is *processing units*. Despite that, it was decided that “thread” was an appropriate term to refer to this concept. The primary factors that drove this decision include: (1) the need for a conceptual entity that can “own” locks, and (2) that this concept is important for discussing thread safety without substituting every mention of “thread” with “task or interrupt handler”.
 
 [TI-RTOS]: http://software-dl.ti.com/lprf/simplelink_cc13x0_sdk/1_30_00_06/exports/docs/ti154stack/ti154stack-sdg/ti154stack-sdg/tirtos/rtos-overview.html
 
@@ -388,7 +388,10 @@ The kernel expects that timer interrupts are handled in a timely manner. The res
 
 <div class="admonition-follows"></div>
 
-> **Relation to Other Specifications:** There are many major design choices when it comes to kernel timing and timed APIs, and they are quite diverse between operating system or kernel specifications. The following list shows some of them:
+> <details>
+> <summary>Relation to Other Specifications</summary>
+>
+> There are many major design choices when it comes to kernel timing and timed APIs, and they are quite diverse between operating system or kernel specifications. The following list shows some of them:
 >
 >  1. *What time unit does the application-facing API use?* In embedded operating systems, it's very common to expose internal ticks and provide C macros to convert real time values into ticks. The conversion is prone to unexpected rounding and integer overflow, and this sort of error is easy to go unnoticed. (For instance, `pdMS_TO_TICKS` from FreeRTOS uses `uint32_t` for intermediate value calculation, and `gcc` won't report overflow even with `-Wall` because `uint32_t` is defined to exhibit a wrap-around behavior. `z_tmcvt` from Zephyr doesn't detect overflow.) Even if it could be detected statically (which is never true for dynamically calculated values), the range of real time values that doesn't cause overflow varies between target systems, harming the portability of software components written for the operating system (how often this cause a problem is debatable).
 >
@@ -432,6 +435,8 @@ The kernel expects that timer interrupts are handled in a timely manner. The res
 > | [μITRON4.0]        | unspecified             | N/A                 | no    | no  | unspecified bits | N/A           |
 > | μT-Kernel 3.0      | milli- or micro-seconds | ?                   | no    | no  | 32 or 64 bits    | ?             |
 > | **R3**             | microseconds            | fixed, microseconds | yes   | no  | 31 bits          | 32 bits       |
+>
+> </details>
 
 [μITRON4.0]: http://www.ertl.jp/ITRON/SPEC/mitron4-e.html
 [AUTOSAR OS 4.3.1]: https://www.autosar.org/fileadmin/user_upload/standards/classic/4-3/AUTOSAR_SWS_OS.pdf
