Merge pull request #1242 from UncleGrump/docs_API_updates

Docs API updates

Updates the documentation restructured text skeleton files with missing
functions and other elements that have been documented in source files.
Some structs, functions, and types that Doxygen cannot parse correctly now have
manually created entries added to the restructured text files. Minor enhancement
to the way the downloads and versions menu is displayed.

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/_templates/versions.html

@@ -11,14 +11,14 @@
 {# Add rst-badge after rst-versions for small badge style. #}
   <div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
     <span class="rst-current-version" data-toggle="rst-current-version">
-      <span class="fa fa-book">AtomVM Docs</span>
-      v: {{ current_version }}
+      <span class="fa fa-download"></span><span class="fa fa-book"> AtomVM Docs version:</span>
+      {{ current_version }}
       <span class="fa fa-caret-down"></span>
     </span>
     <div class="rst-other-versions">
       {% if versions|length >= 1 %}
       <dl>
-        <dt>{{ _('Versions') }}</dt>
+        <dt><span class="fa fa-book">{{ _(' Versions') }}</span></dt>
         {% for slug, url in versions %}
           {% if slug == current_version %} <strong> {% endif %}
           <dd><a href="{{ url }}">{{ slug }}</a></dd>
@@ -28,7 +28,7 @@
       {% endif %}
       {% if downloads|length >= 1 %}
       <dl>
-        <dt>{{ _('Downloads') }}</dt>
+        <dt><span class="fa fa-download">{{ _(' Downloads') }}</span></dt>
         {% for type, url in downloads %}
           <dd><a href="{{ url }}">{{ type }}</a></dd>
         {% endfor %}

doc/src/apidocs/libatomvm/data_structures.rst

@@ -12,7 +12,7 @@ Data Structures
 ---------------------
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :caption: Structs
 
 .. doxygenstruct:: AtomsHashTable
@@ -55,24 +55,46 @@ Data Structures
    :allow-dot-graphs:
 .. doxygenstruct:: Heap
    :allow-dot-graphs:
-.. doxygenstruct:: HNode
-   :allow-dot-graphs:
+.. Doxygen mangles this structure when parsing atomshashtable.c.
+.. c:struct:: HNode
+
+   **Public Members**
+
+   .. c:var:: struct HNode *next
+   .. c:var:: AtomString key
+   .. c:var:: unsigned long value
+
 .. doxygenstruct:: HNodeGroup
    :allow-dot-graphs:
 .. doxygenstruct:: IFFRecord
    :allow-dot-graphs:
 .. doxygenstruct:: InMemoryAVMPack
    :allow-dot-graphs:
-.. doxygenstruct:: Int24
-   :allow-dot-graphs:
-.. doxygenstruct:: Int40
-   :allow-dot-graphs:
-.. doxygenstruct:: Int48
-   :allow-dot-graphs:
-.. doxygenstruct:: Int56
-   :allow-dot-graphs:
-.. doxygenstruct:: kv_pair
-   :allow-dot-graphs:
+.. defined in excluded opcodesswitch.h
+.. c:struct:: Int24
+
+   .. c:var:: int32_t val24 : 24
+
+.. c:struct:: Int40
+
+   .. c:var:: int64_t val40 : 40
+
+.. c:struct:: Int48
+
+   .. c:var:: int64_t val48 : 48
+
+.. c:struct:: Int56
+
+   .. c:var:: int64_t val56 : 56
+
+.. c:struct:: kv_pair
+
+   **Public Members**
+
+   .. c:var:: term key
+   .. c:var:: term value
+
+.. end of opcodesswitch.h structs
 .. doxygenstruct:: LineRefOffset
    :allow-dot-graphs:
 .. doxygenstruct:: ListHead
@@ -116,8 +138,6 @@ Data Structures
    :allow-dot-graphs:
 .. doxygenstruct:: SyncList
    :allow-dot-graphs:
-.. doxygenstruct:: TempStack
-   :allow-dot-graphs:
 .. doxygenstruct:: TermSignal
    :allow-dot-graphs:
 .. doxygenstruct:: TimerList
@@ -164,7 +184,6 @@ Enumerations
 .. doxygenenum:: OpenAVMResult
 .. doxygenenum:: RefcBinaryFlags
 .. doxygenenum:: SocketErrors
-.. doxygenenum:: TempStackResult
 .. doxygenenum:: TermCompareOpts
 .. doxygenenum:: TermCompareResult
 .. doxygenenum:: UnicodeConversionResult

doc/src/apidocs/libatomvm/functions.rst

@@ -4,6 +4,7 @@
 
 :orphan:
 
+.. c:namespace:: NULL
 .. c:namespace:: libAtomVM
 .. c:namespace-push:: functions
 
@@ -24,13 +25,22 @@ Functions
 .. doxygenfunction:: avmpack_find_section_by_name
 .. doxygenfunction:: avmpack_fold
 .. doxygenfunction:: avmpack_is_valid
+.. doxygenfunction:: bitstring_copy_bits
 .. doxygenfunction:: bitstring_copy_bits_incomplete_bytes
+.. doxygenfunction:: bitstring_insert_utf16
+.. doxygenfunction:: bitstring_insert_utf32
+.. doxygenfunction:: bitstring_insert_utf8
+.. doxygenfunction:: bitstring_match_utf16
+.. doxygenfunction:: bitstring_match_utf32
+.. doxygenfunction:: bitstring_match_utf8
 .. doxygenfunction:: bitstring_utf16_decode
 .. doxygenfunction:: bitstring_utf16_encode
+.. doxygenfunction:: bitstring_utf16_size
 .. doxygenfunction:: bitstring_utf32_decode
 .. doxygenfunction:: bitstring_utf32_encode
 .. doxygenfunction:: bitstring_utf8_decode
 .. doxygenfunction:: bitstring_utf8_encode
+.. doxygenfunction:: bitstring_utf8_size
 .. doxygenfunction:: context_avail_free_memory
 .. doxygenfunction:: context_clean_registers
 .. doxygenfunction:: context_destroy
@@ -76,6 +86,21 @@ Functions
 .. doxygenfunction:: externalterm_from_binary
 .. doxygenfunction:: externalterm_to_binary
 .. doxygenfunction:: externalterm_to_term
+.. TODO: figure out why  Doxgen cant find externalterm_to_term_internal in externalterm.c
+.. c:function:: static term externalterm_to_term_internal(const void *external_term, size_t size, Context *ctx, ExternalTermOpts opts, size_t *bytes_read, bool copy)
+
+   Copy an external term to internal storage.
+
+   :param external_term: buffer containing external term
+   :param size:          size of the external_term
+   :param ctx:           current context in which terms may be stored
+   :param opts:          additional opts, such as ExternalTermToHeapFragment for storing parsed
+                         terms in a heap fragment, otherwise terms are stored in the context heap.
+   :param bytes_read:    the number of bytes read off external_term in order to yield a term
+   :param copy:          whether to copy binary data and atom strings (pass `true`, unless
+                         `external_term` is a const binary and will not be deallocated)
+   :returns:             the parsed term
+
 .. doxygenfunction:: globalcontext_atomstring_from_term
 .. doxygenfunction:: globalcontext_demonitor
 .. doxygenfunction:: globalcontext_destroy
@@ -96,6 +121,8 @@ Functions
 .. doxygenfunction:: globalcontext_maybe_unregister_process_id
 .. doxygenfunction:: globalcontext_new
 .. doxygenfunction:: globalcontext_process_exists
+.. doxygenfunction:: globalcontext_process_task_driver_queues
+.. doxygenfunction:: globalcontext_refc_decrement_refcount_from_task
 .. doxygenfunction:: globalcontext_register_process
 .. doxygenfunction:: globalcontext_send_message
 .. doxygenfunction:: globalcontext_send_message_from_task
@@ -118,6 +145,7 @@ Functions
 .. doxygenfunction:: mailbox_has_next
 .. doxygenfunction:: mailbox_init
 .. doxygenfunction:: mailbox_len
+.. doxygenfunction:: mailbox_message_create_from_term
 .. doxygenfunction:: mailbox_message_dispose
 .. doxygenfunction:: mailbox_next
 .. doxygenfunction:: mailbox_peek
@@ -136,11 +164,16 @@ Functions
 .. doxygenfunction:: memory_copy_term_tree_to_storage
 .. doxygenfunction:: memory_destroy_heap
 .. doxygenfunction:: memory_destroy_heap_fragment
+.. doxygenfunction:: memory_destroy_heap_from_task
+.. doxygenfunction:: memory_ensure_free_opt
 .. doxygenfunction:: memory_ensure_free_with_roots
+.. doxygenfunction:: memory_erl_nif_env_ensure_free
 .. doxygenfunction:: memory_estimate_usage
+.. doxygenfunction:: memory_heap_alloc
 .. doxygenfunction:: memory_heap_append_fragment
 .. doxygenfunction:: memory_heap_append_heap
 .. doxygenfunction:: memory_heap_fragment_memory_size
+.. doxygenfunction:: memory_heap_trim
 .. doxygenfunction:: memory_heap_youngest_size
 .. doxygenfunction:: memory_heap_memory_size
 .. doxygenfunction:: memory_init_heap
@@ -157,6 +190,7 @@ Functions
 .. doxygenfunction:: module_new_from_iff_binary
 .. doxygenfunction:: module_resolve_function
 .. doxygenfunction:: module_search_exported_function
+.. doxygenfunction:: otp_socket_lwip_enqueue
 .. doxygenfunction:: platform_nifs_get_nif
 .. doxygenfunction:: posix_errno_to_term
 .. doxygenfunction:: process_listener_handler

doc/src/apidocs/libatomvm/index.rst

@@ -20,7 +20,7 @@ libAtomVM
    macros
 
 -------------------------
-libAtomVM Header Files
+libAtomVM source files
 -------------------------
 
 .. toctree::

doc/src/apidocs/libatomvm/types.rst

@@ -23,6 +23,16 @@ Types
 .. doxygentypedef:: avm_uint64_t
 .. doxygentypedef:: avm_uint_t
 .. doxygentypedef:: avmpack_fold_fun
+.. from exclided opcodesshwitch.h
+.. c:type:: term* dreg_t
+
+.. c:type:: dreg_gc_safe_t
+
+   .. c:struct:: _
+
+      .. c:var:: term *base
+      .. c:var:: int index
+
 .. doxygentypedef:: ERL_NIF_TERM
 .. doxygentypedef:: ErlNifEvent
 .. doxygentypedef:: ErlNifMonitor
@@ -33,4 +43,15 @@ Types
 .. doxygentypedef:: ErlNifResourceType
 .. doxygentypedef:: event_handler_t
 .. doxygentypedef:: EventListener
+.. TODO: find out why Doxygen can parse this from mailbox.h
+.. c:type:: MailboxMessage MailboxMessage
+
+   .. c:struct:: MailboxMessage
+
+      .. c:var:: MailboxMessage *next
+      .. c:union:: _
+
+         .. c:var:: enum MessageType type
+         .. c:var:: term *heap_fragment_end
+
 .. doxygentypedef:: term