Refactor overflow handling and function pointer notes

cleaned up some links and stuff

Author: rcseacord

src/coding-guidelines/types-and-traits.rst

@@ -25,20 +25,21 @@ Types and Traits
       :status: draft
 
       In debug builds, Rust performs runtime checks for integer overflow and will panic if detected.
-      However, in release builds (with optimizations enabled), unless the flag `overflow-checks`_ is
-      turned on, integer operations silently wrap around on overflow, creating potential for silent
-      failures and security vulnerabilities. Note that overflow-checks only brings the default panic
-      behavior from debug into release builds, avoiding potential silent wrap arounds. Nonetheless,
-      abrupt program termination is usually not suitable and, therefore, turning this flag on must
-      not be used as a substitute of explicit handling. Furthermore, the behavior in release mode is
-      under consideration by the The Rust Language Design Team and in the future overflow checking
+      However, in release builds (with optimizations enabled),
+      unless the flag `overflow-checks`_ is turned on, integer operations silently wrap around on overflow,
+      creating potential for silent failures and security vulnerabilities.
+      Note that overflow-checks only brings the default panic behavior from debug into release builds,
+      avoiding potential silent wrap arounds.
+      Nonetheless, abrupt program termination is not suitable and, therefore, turning this flag on must
+      not be used as a substitute of explicit handling.
+      Furthermore, the behavior in release mode is under consideration by the The Rust Language Design Team and in the future overflow checking
       may be turned on by default in release builds (it is a `frequently requested change`_).
 
-      .. _overflow-checks: https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/codegen-options/index.md#overflow-checks
-      .. _frequently requested change: https://lang-team.rust-lang.org/frequently-requested-changes.html#numeric-overflow-checking-should-be-on-by-default-even-in-release-mode
+      .. `overflow-checks <https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/codegen-options/index.md#overflow-checks>`_
+      .. `frequently requested change <https://lang-team.rust-lang.org/frequently-requested-changes.html#numeric-overflow-checking-should-be-on-by-default-even-in-release-mode>`_
 
-      Safety-critical software requires consistent and predictable behavior across all build
-      configurations. Explicit handling of potential overflow conditions improves code clarity,
+      Safety-critical software requires consistent and predictable behavior across all build configurations.
+      Explicit handling of potential overflow conditions improves code clarity,
       maintainability, and reduces the risk of numerical errors in production.
 
    .. non_compliant_example::
@@ -73,9 +74,15 @@ Types and Traits
     :scope: system
     :tags: surprising-behavior
 
-    Do not rely on the equality or stable identity of function pointers originating from different crates or that may be inlined, duplicated, or instantiated differently across compilation units, codegen units, or optimization profiles.
+    Do not rely on the equality or stable identity of function pointers originating from different crates or that may be inlined,
+    duplicated, or instantiated differently across compilation units, codegen units, or optimization profiles.
 
-    Avoid assumptions about low-level metadata (such as symbol addresses) unless explicitly guaranteed by the Ferrocene Language Specification (FLS). Function address identity is not guaranteed by Rust and must not be treated as stable. Rust’s fn type is a zero-sized function item promoted to a function pointer, whose address is determined by the compiler backend. When a function resides in a different crate, or when optimizations such as inlining, link-time optimization, or codegen-unit partitioning are enabled, the compiler may generate multiple distinct code instances for the same function or alter the address at which it is emitted.
+    Avoid assumptions about low-level metadata (such as symbol addresses) unless explicitly guaranteed by the Ferrocene Language Specification (FLS).
+    Function address identity is not guaranteed by Rust and must not be treated as stable.
+    Rust’s ``fn`` type is a zero-sized function item promoted to a function pointer, whose address is determined by the compiler backend.
+    When a function resides in a different crate, or when optimizations such as inlining,
+    link-time optimization, or codegen-unit partitioning are enabled,
+    the compiler may generate multiple distinct code instances for the same function or alter the address at which it is emitted.
 
     Consequently, the following operations are not reliable:
 
@@ -90,33 +97,36 @@ Types and Traits
         :id: rat_xcVE5Hfnbb2u 
         :status: draft
 
-        Compiler optimizations may cause function pointers originating from different crates to lose stable identity. Observed behaviors include:
+        Compiler optimizations may cause function pointers originating from different crates to lose stable identity.
+        Observed behaviors include:
 
         - Cross-crate inlining producing multiple code instantiations
         - Codegen-unit separation causing function emission in multiple units
         - Incremental builds producing variant symbol addresses
         - Link-time optimization merging or splitting functions unpredictably
 
-        This behavior has resulted in real-world issues, such as the bug reported in rust-lang/rust#117047,
-	where function pointer comparisons unexpectedly failed due to cross-crate inlining.
+        This behavior has resulted in real-world issues,
+        such as the bug reported in `rust-lang/rust#117047 <https://github.com/rust-lang/rust/issues/117047>`_,
+        where function pointer comparisons unexpectedly failed due to cross-crate inlining.
 
         Violating this rule may cause:
 
         - Silent logic failures: callbacks not matching, dispatch tables misbehaving.
         - Inappropriate branching: identity-based dispatch selecting wrong handler.
         - Security issues: adversary-controlled conditions bypassing function-based authorization/dispatch logic.
         - Nondeterministic behavior: correctness depending on build flags or incremental state.
-        - Test-only correctness: function pointer equality passing in debug builds but failing in release/LTO builds.
+        - Test-only correctness: function pointer equality passing in debug builds but failing in release/link-time optimization builds.
 
-        In short, dependence on function address stability introduces non-portable, build-profile-dependent behavior, which is incompatible with high-integrity Rust.
+        In short, dependence on function address stability introduces non-portable, build-profile-dependent behavior,
+        which is incompatible with high-integrity Rust.
 
     .. non_compliant_example::
         :id: non_compl_ex_MkAkFxjRTijx 
         :status: draft
 
         Due to cross-crate inlining or codegen-unit partitioning,
-	the address of ``handler_a`` in crate ``B`` may differ from its address in crate A,
-	causing comparisons to fail as shown in this noncompliant code example:
+        the address of ``handler_a`` in crate ``B`` may differ from its address in crate A,
+	    causing comparisons to fail as shown in this noncompliant code example:
 
         .. code-block:: rust
 
@@ -187,15 +197,15 @@ Types and Traits
 
             let f = op_mul;
 
-            // ❌ Lookup may fail if `op_mul` has multiple emitted instances.
+            // Error: Lookup may fail if `op_mul` has multiple emitted instances.
             assert_eq!(registry.get(&f), Some(&"double"));
 
     .. compliant_example::
         :id: compl_ex_oiqSSclTXmIj 
         :status: draft
 
         This compliant example uses a stable identity wrappers as identity keys.
-	The ``id`` is a stable, programmer-defined identity, immune to compiler optimizations.
+	    The ``id`` is a stable, programmer-defined identity, immune to compiler optimizations.
         The function pointer is preserved for behavior (``func``) but never used as the identity key.
 
         .. code-block:: rust
@@ -254,7 +264,7 @@ Types and Traits
                 }
             }
 
-            register(handler); // Error: ❌ may be inserted twice under some builds
+            register(handler); // Error: may be inserted twice under some builds
 
     .. compliant_example::
         :id: compl_ex_oiqSSclTXmIk