Merge pull request #1945 from bettio/stubbed-functions-doc

doc: add page for stubbed functions

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

doc/src/differences-with-beam.md

@@ -81,6 +81,8 @@ changes.
 Please check AtomVM's [standard library documentation](./apidocs/erlang/estdlib/README.md) to find out differences
 and limitations of each module.
 
+See also [stubbed functions](./stubbed-functions.md) list.
+
 ### OTP architecture
 
 Support for OTP applications is currently very limited. `gen_server`, `gen_statem` and `supervisor`

doc/src/index.rst

@@ -30,6 +30,7 @@ AtomVM includes many advanced features, including process spawning, monitoring,
    network-programming-guide
    distributed-erlang
    differences-with-beam
+   stubbed-functions
    build-instructions
    atomvm-internals
    memory-management

doc/src/stubbed-functions.md

@@ -0,0 +1,60 @@
+<!--
+ Copyright 2025 AtomVM Contributors
+
+ SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
+-->
+
+# Stubbed Functions
+
+AtomVM implements stub functions for certain BEAM operations that are either not applicable to
+embedded environments, not yet implemented, or intentionally left as no-ops for compatibility
+reasons. These functions allow BEAM code that references them to load and execute without errors,
+even though the actual functionality may not be present.
+
+## Purpose of Stubbed Functions
+
+Stubbed functions serve several purposes in AtomVM:
+
+1. **Compatibility**: Allow BEAM modules that use these functions to work anyway
+2. **Environment Differences**: Functions that make no sense in embedded contexts (or in AtomVM)
+but are required for code compatibility
+3. **Performance**: Operations that would be too expensive on microcontrollers and are safely
+ignored
+
+## List of Stubbed Functions
+
+The following functions are currently stubbed in AtomVM and always return a fixed value:
+
+<!--
+### Foo Bar Functions
+
+| Module | Function | Return Value | Notes |
+|--------|----------|--------------|-------|
+| `erlang` | `foo/0` | `[]` | Not applicable on AtomVM |
+-->
+
+## Important Considerations
+
+When using AtomVM, be aware that stubbed functions will not provide the functionality you might
+expect from BEAM. Code that relies on these functions for critical behavior will need to be adapted
+for the AtomVM environment.
+
+## Detecting Stubbed Functions
+
+To write portable code that works on both BEAM and AtomVM, you can detect the runtime environment:
+
+```erlang
+case erlang:system_info(machine) of
+    "BEAM" ->
+        %% Use full functionality
+        full_implementation();
+    "ATOM" ->
+        %% Use alternative approach or skip
+        alternative_implementation()
+end
+```
+
+## Future Implementations
+
+Some stubbed functions may be implemented in future versions of AtomVM. Use
+[GitHub issues](https://github.com/atomvm/AtomVM/issues) for providing any kind of feedback.