From 25b8bc7c4bbd914f27d745bea07e0bc66c9841b1 Mon Sep 17 00:00:00 2001 From: "Claudius \"keldu\" Holeksa" Date: Sat, 7 Nov 2026 17:48:43 +0100 Subject: Core oos docs --- docs_oos/data/core/array_buffer.json | 31 ++++ docs_oos/data/core/branch.json | 103 +++++++++++++ docs_oos/data/core/buffer.json | 182 +++++++++++++++++++++++ docs_oos/data/core/buffer_view.json | 74 +++++++++ docs_oos/data/core/chain_array_buffer.json | 50 +++++++ docs_oos/data/core/err/already_exists.json | 35 +++++ docs_oos/data/core/err/buffer_exhausted.json | 35 +++++ docs_oos/data/core/err/critical.json | 37 +++++ docs_oos/data/core/err/invalid_state.json | 35 +++++ docs_oos/data/core/err/no_error.json | 38 +++++ docs_oos/data/core/err/not_found.json | 38 +++++ docs_oos/data/core/err/not_implemented.json | 40 +++++ docs_oos/data/core/err/not_supported.json | 40 +++++ docs_oos/data/core/err/out_of_memory.json | 38 +++++ docs_oos/data/core/err/recoverable.json | 35 +++++ docs_oos/data/core/error.json | 168 +++++++++++++++++++++ docs_oos/data/core/error_builder.json | 65 ++++++++ docs_oos/data/core/error_or.json | 110 ++++++++++++++ docs_oos/data/core/error_or.nested.json | 24 +++ docs_oos/data/core/error_or_value.json | 26 ++++ docs_oos/data/core/heap.json | 23 +++ docs_oos/data/core/id.json | 67 +++++++++ docs_oos/data/core/lent.json | 21 +++ docs_oos/data/core/maybe.json | 21 +++ docs_oos/data/core/our.json | 24 +++ docs_oos/data/core/own.json | 30 ++++ docs_oos/data/core/parameter_key_pack_index.json | 35 +++++ docs_oos/data/core/parameter_key_pack_type.json | 32 ++++ docs_oos/data/core/parameter_pack_index.json | 32 ++++ docs_oos/data/core/parameter_pack_type.json | 27 ++++ docs_oos/data/core/parameter_pack_value.json | 33 ++++ docs_oos/data/core/ptr.json | 64 ++++++++ docs_oos/data/core/ref.json | 47 ++++++ docs_oos/data/core/ring_buffer.json | 55 +++++++ docs_oos/data/core/share.json | 25 ++++ docs_oos/data/core/string_literal.json | 74 +++++++++ docs_oos/data/core/tmpl_concat.json | 34 +++++ docs_oos/data/core/tmpl_group.json | 39 +++++ docs_oos/data/core/tmpl_reduce.json | 31 ++++ docs_oos/data/core/tmpl_value_group.json | 41 +++++ docs_oos/data/core/tree.json | 75 ++++++++++ docs_oos/data/core/tree_container.json | 78 ++++++++++ docs_oos/data/core/void_t.json | 20 +++ docs_oos/entity.schema.json | 39 +++-- 44 files changed, 2159 insertions(+), 12 deletions(-) create mode 100644 docs_oos/data/core/array_buffer.json create mode 100644 docs_oos/data/core/branch.json create mode 100644 docs_oos/data/core/buffer.json create mode 100644 docs_oos/data/core/buffer_view.json create mode 100644 docs_oos/data/core/chain_array_buffer.json create mode 100644 docs_oos/data/core/err/already_exists.json create mode 100644 docs_oos/data/core/err/buffer_exhausted.json create mode 100644 docs_oos/data/core/err/critical.json create mode 100644 docs_oos/data/core/err/invalid_state.json create mode 100644 docs_oos/data/core/err/no_error.json create mode 100644 docs_oos/data/core/err/not_found.json create mode 100644 docs_oos/data/core/err/not_implemented.json create mode 100644 docs_oos/data/core/err/not_supported.json create mode 100644 docs_oos/data/core/err/out_of_memory.json create mode 100644 docs_oos/data/core/err/recoverable.json create mode 100644 docs_oos/data/core/error.json create mode 100644 docs_oos/data/core/error_builder.json create mode 100644 docs_oos/data/core/error_or.json create mode 100644 docs_oos/data/core/error_or.nested.json create mode 100644 docs_oos/data/core/error_or_value.json create mode 100644 docs_oos/data/core/heap.json create mode 100644 docs_oos/data/core/id.json create mode 100644 docs_oos/data/core/lent.json create mode 100644 docs_oos/data/core/maybe.json create mode 100644 docs_oos/data/core/our.json create mode 100644 docs_oos/data/core/own.json create mode 100644 docs_oos/data/core/parameter_key_pack_index.json create mode 100644 docs_oos/data/core/parameter_key_pack_type.json create mode 100644 docs_oos/data/core/parameter_pack_index.json create mode 100644 docs_oos/data/core/parameter_pack_type.json create mode 100644 docs_oos/data/core/parameter_pack_value.json create mode 100644 docs_oos/data/core/ptr.json create mode 100644 docs_oos/data/core/ref.json create mode 100644 docs_oos/data/core/ring_buffer.json create mode 100644 docs_oos/data/core/share.json create mode 100644 docs_oos/data/core/string_literal.json create mode 100644 docs_oos/data/core/tmpl_concat.json create mode 100644 docs_oos/data/core/tmpl_group.json create mode 100644 docs_oos/data/core/tmpl_reduce.json create mode 100644 docs_oos/data/core/tmpl_value_group.json create mode 100644 docs_oos/data/core/tree.json create mode 100644 docs_oos/data/core/tree_container.json create mode 100644 docs_oos/data/core/void_t.json diff --git a/docs_oos/data/core/array_buffer.json b/docs_oos/data/core/array_buffer.json new file mode 100644 index 0000000..24b5cca --- /dev/null +++ b/docs_oos/data/core/array_buffer.json @@ -0,0 +1,31 @@ +{ + "format": 1, + "id": "saw-array_buffer", + "kind": "class", + "name": "array_buffer", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/buffer.hpp", + "brief_description": "One time buffer.", + "detailed_description": [ + [ + "Filled once and read once. The cursors only move forward and the storage is never reused, so what was read is gone and what was written cannot be taken back." + ], + [ + "The right choice for a single message of known size." + ] + ], + "bases": [ + [{"name": "buffer", "id": "saw-buffer"}] + ], + "functions": { + "saw-array_buffer-ctor": { + "id": "saw-array_buffer-ctor", + "name": "array_buffer", + "type": [], + "parameters": [ + {"name": "size", "type": ["size_t"]} + ] + } + } +} diff --git a/docs_oos/data/core/branch.json b/docs_oos/data/core/branch.json new file mode 100644 index 0000000..d30c42f --- /dev/null +++ b/docs_oos/data/core/branch.json @@ -0,0 +1,103 @@ +{ + "format": 1, + "id": "saw-branch", + "kind": "class", + "name": "branch", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/tree.hpp", + "brief_description": "Container with a simplistic approach to a branch.", + "detailed_description": [ + [ + "The edge in a", + {"name": "tree_container", "id": "saw-tree_container"}, + "It holds either a leaf value or a whole sub tree, as a variant of the two, so the recursion lives in the data rather than in a pointer chain." + ], + [ + "Access comes in two flavours: get asserts what is held, while extract and replace hand the content out or swap it and report a mismatch as an error instead." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "Leaf value type."}, + {"name": "Tree", "kind": "type", "brief_description": "Sub tree type."} + ], + "aliases": { + "saw-branch-type": { + "id": "saw-branch-type", + "name": "type", + "type": ["std::variant< Tree, T >"], + "brief_description": "Either a sub tree or a leaf." + } + }, + "functions": { + "saw-branch-is": { + "id": "saw-branch-is", + "name": "is", + "type": ["bool"], + "const": true, + "brief_description": "Whether the branch holds the given alternative.", + "templates": [ + {"name": "NT", "kind": "type"} + ] + }, + "saw-branch-is_tree": { + "id": "saw-branch-is_tree", + "name": "is_tree", + "type": ["bool"], + "const": true, + "brief_description": "Whether the branch continues into a sub tree." + }, + "saw-branch-is_value": { + "id": "saw-branch-is_value", + "name": "is_value", + "type": ["bool"], + "const": true, + "brief_description": "Whether the branch ends in a leaf." + }, + "saw-branch-get_tree": { + "id": "saw-branch-get_tree", + "name": "get_tree", + "type": ["Tree &"], + "brief_description": "The sub tree. Only valid if is_tree." + }, + "saw-branch-get_value": { + "id": "saw-branch-get_value", + "name": "get_value", + "type": ["T &"], + "brief_description": "The leaf. Only valid if is_value." + }, + "saw-branch-extract_tree": { + "id": "saw-branch-extract_tree", + "name": "extract_tree", + "type": ["error_or< Tree >"], + "brief_description": "Takes the sub tree out, failing if the branch holds a leaf." + }, + "saw-branch-extract_value": { + "id": "saw-branch-extract_value", + "name": "extract_value", + "type": ["error_or< T >"], + "brief_description": "Takes the leaf out, failing if the branch holds a sub tree." + }, + "saw-branch-replace_tree": { + "id": "saw-branch-replace_tree", + "name": "replace_tree", + "type": ["error_or< Tree >"], + "brief_description": "Swaps in new content and returns the sub tree which was there.", + "parameters": [ + {"name": "nd", "type": ["type"]} + ] + }, + "saw-branch-replace_value": { + "id": "saw-branch-replace_value", + "name": "replace_value", + "type": ["error_or< T >"], + "brief_description": "Swaps in new content and returns the leaf which was there.", + "parameters": [ + {"name": "nd", "type": ["type"]} + ] + } + }, + "notes": [ + "Copy is forbidden, move is allowed." + ] +} diff --git a/docs_oos/data/core/buffer.json b/docs_oos/data/core/buffer.json new file mode 100644 index 0000000..cee07fd --- /dev/null +++ b/docs_oos/data/core/buffer.json @@ -0,0 +1,182 @@ +{ + "format": 1, + "id": "saw-buffer", + "kind": "class", + "name": "buffer", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/buffer.hpp", + "brief_description": "Access class to reduce templated buffer segment bloat.", + "detailed_description": [ + [ + "A buffer has two independent cursors, one for reading and one for writing, and may be split into segments which are contiguous only up to a point. Everything is phrased around that: composite length is what remains in total, segment length is what remains without a jump." + ], + [ + "Code which copies in bulk loops on the segment length; code which works byte by byte uses read and write with an offset. Both cursors move only through the advance calls, so a reader can look ahead without consuming." + ] + ], + "functions": { + "saw-buffer-read_position": { + "id": "saw-buffer-read_position", + "name": "read_position", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "Where the read cursor currently is." + }, + "saw-buffer-read_composite_length": { + "id": "saw-buffer-read_composite_length", + "name": "read_composite_length", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "How many bytes can be read in total, across segments." + }, + "saw-buffer-read_segment_length": { + "id": "saw-buffer-read_segment_length", + "name": "read_segment_length", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "How many bytes can be read contiguously from an offset.", + "parameters": [ + {"name": "offset", "type": ["size_t"], "default": "0"} + ] + }, + "saw-buffer-read_advance": { + "id": "saw-buffer-read_advance", + "name": "read_advance", + "type": ["void"], + "virtual": true, + "brief_description": "Consumes bytes from the read side.", + "parameters": [ + {"name": "bytes", "type": ["size_t"]} + ] + }, + "saw-buffer-read": { + "id": "saw-buffer-read", + "name": "read", + "type": ["uint8_t &"], + "virtual": true, + "brief_description": "The byte at an offset from the read cursor, without consuming it.", + "parameters": [ + {"name": "i", "type": ["size_t"], "default": "0"} + ] + }, + "saw-buffer-write_position": { + "id": "saw-buffer-write_position", + "name": "write_position", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "Where the write cursor currently is." + }, + "saw-buffer-write_composite_length": { + "id": "saw-buffer-write_composite_length", + "name": "write_composite_length", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "How many bytes can be written in total, across segments." + }, + "saw-buffer-write_segment_length": { + "id": "saw-buffer-write_segment_length", + "name": "write_segment_length", + "type": ["size_t"], + "const": true, + "virtual": true, + "brief_description": "How many bytes can be written contiguously from an offset.", + "parameters": [ + {"name": "offset", "type": ["size_t"], "default": "0"} + ] + }, + "saw-buffer-write_advance": { + "id": "saw-buffer-write_advance", + "name": "write_advance", + "type": ["void"], + "virtual": true, + "brief_description": "Marks bytes as written.", + "parameters": [ + {"name": "bytes", "type": ["size_t"]} + ] + }, + "saw-buffer-write": { + "id": "saw-buffer-write", + "name": "write", + "type": ["uint8_t &"], + "virtual": true, + "brief_description": "The byte at an offset from the write cursor.", + "parameters": [ + {"name": "i", "type": ["size_t"], "default": "0"} + ] + }, + "saw-buffer-write_require_length": { + "id": "saw-buffer-write_require_length", + "name": "write_require_length", + "type": [{"name": "error", "id": "saw-error"}], + "virtual": true, + "brief_description": "Asks for room before writing in bulk.", + "detailed_description": [ + [ + "Nothing can be done if the read side has not been filled, but the write side can grow on demand. Call this before pushing a run of bytes, so a failure happens once up front instead of halfway through." + ] + ], + "parameters": [ + {"name": "bytes", "type": ["size_t"]} + ] + }, + "saw-buffer-push-1": { + "id": "saw-buffer-push-1", + "name": "push", + "type": [{"name": "error", "id": "saw-error"}], + "brief_description": "Writes one byte.", + "detailed_description": [ + ["Fails with", {"name": "buffer_exhausted", "id": "saw-err-buffer_exhausted"}, "if there is no room."] + ], + "parameters": [ + {"name": "value", "type": ["const uint8_t &"]} + ] + }, + "saw-buffer-push-2": { + "id": "saw-buffer-push-2", + "name": "push", + "type": [{"name": "error", "id": "saw-error"}], + "brief_description": "Writes a run of bytes, segment by segment.", + "parameters": [ + {"name": "buffer", "type": ["const uint8_t &"], "brief_description": "First byte of the run."}, + {"name": "size", "type": ["size_t"]} + ] + }, + "saw-buffer-pop-1": { + "id": "saw-buffer-pop-1", + "name": "pop", + "type": [{"name": "error", "id": "saw-error"}], + "brief_description": "Reads one byte and consumes it.", + "parameters": [ + {"name": "value", "type": ["uint8_t &"]} + ] + }, + "saw-buffer-pop-2": { + "id": "saw-buffer-pop-2", + "name": "pop", + "type": [{"name": "error", "id": "saw-error"}], + "brief_description": "Reads a run of bytes and consumes them.", + "parameters": [ + {"name": "buffer", "type": ["uint8_t &"]}, + {"name": "size", "type": ["size_t"]} + ] + }, + "saw-buffer-write_from": { + "id": "saw-buffer-write_from", + "name": "write_from", + "type": ["error_or< uint64_t >"], + "brief_description": "Reads from another buffer and writes into this one.", + "parameters": [ + {"name": "buff", "type": ["const buffer &"]} + ] + } + }, + "notes": [ + "The concrete buffers differ in what happens when space runs out, which is the thing to pick on." + ] +} diff --git a/docs_oos/data/core/buffer_view.json b/docs_oos/data/core/buffer_view.json new file mode 100644 index 0000000..bf07694 --- /dev/null +++ b/docs_oos/data/core/buffer_view.json @@ -0,0 +1,74 @@ +{ + "format": 1, + "id": "saw-buffer_view", + "kind": "class", + "name": "buffer_view", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/buffer.hpp", + "brief_description": "A viewer class for buffers.", + "detailed_description": [ + [ + "Carries its own cursors over somebody else's", + {"name": "buffer", "id": "saw-buffer"}, + "so a decoder can walk forward, discover the input is incomplete, and leave the underlying buffer untouched. Only once the operation succeeded does the caller advance the real buffer by the view's offset." + ], + [ + "That is the whole speculative parsing mechanism in this codebase. The codecs decode into a view and commit afterwards." + ], + [ + "Working on the referenced buffer invalidates the view." + ] + ], + "bases": [ + [{"name": "buffer", "id": "saw-buffer"}] + ], + "functions": { + "saw-buffer_view-ctor-1": { + "id": "saw-buffer_view-ctor-1", + "name": "buffer_view", + "type": [], + "parameters": [ + {"name": "buffer", "type": [{"name": "buffer", "id": "saw-buffer"}, "&"]} + ] + }, + "saw-buffer_view-ctor-2": { + "id": "saw-buffer_view-ctor-2", + "name": "buffer_view", + "type": [], + "brief_description": "With an upper bound on what may be read and written through it.", + "parameters": [ + {"name": "buffer", "type": [{"name": "buffer", "id": "saw-buffer"}, "&"]}, + {"name": "limit_read_len", "type": ["uint64_t"]}, + {"name": "limit_write_len", "type": ["uint64_t"]} + ] + }, + "saw-buffer_view-read_offset": { + "id": "saw-buffer_view-read_offset", + "name": "read_offset", + "type": ["size_t"], + "const": true, + "brief_description": "How far the view has read ahead of the underlying buffer.", + "detailed_description": [ + ["This is what gets handed to read_advance on the real buffer once the read is known to have succeeded."] + ] + }, + "saw-buffer_view-write_offset": { + "id": "saw-buffer_view-write_offset", + "name": "write_offset", + "type": ["size_t"], + "const": true, + "brief_description": "How far the view has written ahead of the underlying buffer." + } + }, + "examples": [ + { + "title": "Decoding without consuming on failure", + "description": [ + ["The shape every codec uses. If the decode fails, the buffer is left exactly as it was and the caller can try again once more data arrived."] + ], + "language": "cpp", + "code": "buffer_view buff_v{from_decode.get_buffer()};\n\nauto eov = impl::json_decode::decode(buff_v, to_decode, cfg_);\nif(eov.is_error()){\n\treturn std::move(eov.get_error());\n}\n\n/// Only now is the input really consumed.\nfrom_decode.get_buffer().read_advance(buff_v.read_offset());\n" + } + ] +} diff --git a/docs_oos/data/core/chain_array_buffer.json b/docs_oos/data/core/chain_array_buffer.json new file mode 100644 index 0000000..a9459bd --- /dev/null +++ b/docs_oos/data/core/chain_array_buffer.json @@ -0,0 +1,50 @@ +{ + "format": 1, + "id": "saw-chain_array_buffer", + "kind": "class", + "name": "chain_array_buffer", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/buffer.hpp", + "brief_description": "A growing chain of one time buffers.", + "detailed_description": [ + [ + "Holds a deque of", + {"name": "array_buffer", "id": "saw-array_buffer"}, + "so capacity can be added without moving what is already there. This is the buffer for a stream of unknown length, where a ring buffer would run out and a single array buffer would have to be guessed in advance." + ], + [ + "It is also why the buffer interface speaks of segments: a read which crosses from one link to the next is not contiguous, so segment length stops at the boundary." + ] + ], + "bases": [ + [{"name": "buffer", "id": "saw-buffer"}] + ], + "functions": { + "saw-chain_array_buffer-ctor": { + "id": "saw-chain_array_buffer-ctor", + "name": "chain_array_buffer", + "type": [] + }, + "saw-chain_array_buffer-extract_front": { + "id": "saw-chain_array_buffer-extract_front", + "name": "extract_front", + "type": ["error_or<", {"name": "array_buffer", "id": "saw-array_buffer"}, ">"], + "brief_description": "Takes the first link out of the chain instead of copying out of it.", + "detailed_description": [ + [ + "The size has to match what the front link still holds exactly. A partial extraction fails with", + {"name": "invalid_state", "id": "saw-err-invalid_state"}, + "and the caller is told to view and copy instead." + ], + [ + "An empty chain fails with", + {"name": "recoverable", "id": "saw-err-recoverable"} + ] + ], + "parameters": [ + {"name": "size", "type": ["uint64_t"]} + ] + } + } +} diff --git a/docs_oos/data/core/err/already_exists.json b/docs_oos/data/core/err/already_exists.json new file mode 100644 index 0000000..3d6c4ff --- /dev/null +++ b/docs_oos/data/core/err/already_exists.json @@ -0,0 +1,35 @@ +{ + "format": 1, + "id": "saw-err-already_exists", + "kind": "struct", + "name": "already_exists", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Something is already there under that name or id.", + "detailed_description": [ + [ + "Recoverable. Storing into an occupied slot, or binding a second server to an address which is already taken. The existing entry is left untouched, so the caller can decide whether to pick another id or treat it as success." + ] + ], + "attributes": { + "saw-err-already_exists-description": { + "id": "saw-err-already_exists-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Already exists\"" + }, + "saw-err-already_exists-is_critical": { + "id": "saw-err-already_exists-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/err/buffer_exhausted.json b/docs_oos/data/core/err/buffer_exhausted.json new file mode 100644 index 0000000..a8651f1 --- /dev/null +++ b/docs_oos/data/core/err/buffer_exhausted.json @@ -0,0 +1,35 @@ +{ + "format": 1, + "id": "saw-err-buffer_exhausted", + "kind": "struct", + "name": "buffer_exhausted", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "A buffer ran out of room to read or write.", + "detailed_description": [ + [ + "Recoverable, and deliberately so: a decoder hitting the end of what has arrived so far is the normal state of a stream, not a defect. Code which decodes incrementally checks for this kind and waits for more instead of failing." + ] + ], + "attributes": { + "saw-err-buffer_exhausted-description": { + "id": "saw-err-buffer_exhausted-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Buffer Exhausted\"" + }, + "saw-err-buffer_exhausted-is_critical": { + "id": "saw-err-buffer_exhausted-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/err/critical.json b/docs_oos/data/core/err/critical.json new file mode 100644 index 0000000..006d6c7 --- /dev/null +++ b/docs_oos/data/core/err/critical.json @@ -0,0 +1,37 @@ +{ + "format": 1, + "id": "saw-err-critical", + "kind": "struct", + "name": "critical", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Generic critical error.", + "detailed_description": [ + [ + "The counterpart of", + {"name": "recoverable", "id": "saw-err-recoverable"}, + "for a failure the caller is not expected to continue through. Same advice applies: a named kind is worth defining as soon as anything wants to branch on it." + ] + ], + "attributes": { + "saw-err-critical-description": { + "id": "saw-err-critical-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Generic critical error\"" + }, + "saw-err-critical-is_critical": { + "id": "saw-err-critical-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "true" + } + } +} diff --git a/docs_oos/data/core/err/invalid_state.json b/docs_oos/data/core/err/invalid_state.json new file mode 100644 index 0000000..343d218 --- /dev/null +++ b/docs_oos/data/core/err/invalid_state.json @@ -0,0 +1,35 @@ +{ + "format": 1, + "id": "saw-err-invalid_state", + "kind": "struct", + "name": "invalid_state", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Something was not in the state the operation requires.", + "detailed_description": [ + [ + "Critical. The catch all for a situation which should not have been reachable: malformed input where the grammar left no choice, a cast between mismatched class ids, a default constructed result which nobody filled in." + ] + ], + "attributes": { + "saw-err-invalid_state-description": { + "id": "saw-err-invalid_state-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Invalid state\"" + }, + "saw-err-invalid_state-is_critical": { + "id": "saw-err-invalid_state-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "true" + } + } +} diff --git a/docs_oos/data/core/err/no_error.json b/docs_oos/data/core/err/no_error.json new file mode 100644 index 0000000..0fa4974 --- /dev/null +++ b/docs_oos/data/core/err/no_error.json @@ -0,0 +1,38 @@ +{ + "format": 1, + "id": "saw-err-no_error", + "kind": "struct", + "name": "no_error", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "No error has occured.", + "detailed_description": [ + [ + "The absence of a failure, expressed as an error kind so that a function returning a plain", + {"name": "error", "id": "saw-error"}, + "can report success. Preregistered as code zero, which is why failed is defined as not being of this kind." + ] + ], + "attributes": { + "saw-err-no_error-description": { + "id": "saw-err-no_error-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"No error has occured\"", + "brief_description": "The category text. This is the portable identity of the error." + }, + "saw-err-no_error-is_critical": { + "id": "saw-err-no_error-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/err/not_found.json b/docs_oos/data/core/err/not_found.json new file mode 100644 index 0000000..e0e0dee --- /dev/null +++ b/docs_oos/data/core/err/not_found.json @@ -0,0 +1,38 @@ +{ + "format": 1, + "id": "saw-err-not_found", + "kind": "struct", + "name": "not_found", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Something was looked up and is not there.", + "detailed_description": [ + [ + "Recoverable, because asking for something absent is a normal outcome rather than a defect. Used when an id has no value stored under it, or when no server listens on an address." + ], + [ + "One of the three kinds preregistered in the registry." + ] + ], + "attributes": { + "saw-err-not_found-description": { + "id": "saw-err-not_found-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Not found\"" + }, + "saw-err-not_found-is_critical": { + "id": "saw-err-not_found-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/err/not_implemented.json b/docs_oos/data/core/err/not_implemented.json new file mode 100644 index 0000000..2aecf9d --- /dev/null +++ b/docs_oos/data/core/err/not_implemented.json @@ -0,0 +1,40 @@ +{ + "format": 1, + "id": "saw-err-not_implemented", + "kind": "struct", + "name": "not_implemented", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "The operation exists but has no implementation yet.", + "detailed_description": [ + [ + "Critical. A placeholder in a backend or codec which is still being built, so the gap surfaces as a failure at runtime instead of as a link error or, worse, as silently wrong behaviour." + ], + [ + "Distinct from", + {"name": "not_supported", "id": "saw-err-not_supported"}, + "which means the operation is never going to exist for this type." + ] + ], + "attributes": { + "saw-err-not_implemented-description": { + "id": "saw-err-not_implemented-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Not implemented\"" + }, + "saw-err-not_implemented-is_critical": { + "id": "saw-err-not_implemented-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "true" + } + } +} diff --git a/docs_oos/data/core/err/not_supported.json b/docs_oos/data/core/err/not_supported.json new file mode 100644 index 0000000..bb509e7 --- /dev/null +++ b/docs_oos/data/core/err/not_supported.json @@ -0,0 +1,40 @@ +{ + "format": 1, + "id": "saw-err-not_supported", + "kind": "struct", + "name": "not_supported", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "The operation does not apply here and never will.", + "detailed_description": [ + [ + "Recoverable, because the caller can reasonably ask and then do something else. The json decoder uses it for a leading plus on a number, which is valid in some languages and simply not part of json." + ], + [ + "Distinct from", + {"name": "not_implemented", "id": "saw-err-not_implemented"}, + "which means the gap is going to be filled later." + ] + ], + "attributes": { + "saw-err-not_supported-description": { + "id": "saw-err-not_supported-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Not supported\"" + }, + "saw-err-not_supported-is_critical": { + "id": "saw-err-not_supported-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/err/out_of_memory.json b/docs_oos/data/core/err/out_of_memory.json new file mode 100644 index 0000000..47cab53 --- /dev/null +++ b/docs_oos/data/core/err/out_of_memory.json @@ -0,0 +1,38 @@ +{ + "format": 1, + "id": "saw-err-out_of_memory", + "kind": "struct", + "name": "out_of_memory", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "An allocation failed.", + "detailed_description": [ + [ + "Critical. This is what a caught std::bad_alloc or a failed container insert turns into, which is how allocation failure stays inside the error path instead of becoming an exception." + ], + [ + "One of the three kinds preregistered in the registry." + ] + ], + "attributes": { + "saw-err-out_of_memory-description": { + "id": "saw-err-out_of_memory-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Out of memory\"" + }, + "saw-err-out_of_memory-is_critical": { + "id": "saw-err-out_of_memory-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "true" + } + } +} diff --git a/docs_oos/data/core/err/recoverable.json b/docs_oos/data/core/err/recoverable.json new file mode 100644 index 0000000..fecd820 --- /dev/null +++ b/docs_oos/data/core/err/recoverable.json @@ -0,0 +1,35 @@ +{ + "format": 1, + "id": "saw-err-recoverable", + "kind": "struct", + "name": "recoverable", + "namespace": "saw::err", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Generic recoverable error.", + "detailed_description": [ + [ + "For a failure which has no kind of its own and which the caller can act on. Prefer defining a tag struct when the kind means something; a named category is what makes an error distinguishable in another process." + ] + ], + "attributes": { + "saw-err-recoverable-description": { + "id": "saw-err-recoverable-description", + "name": "description", + "type": ["std::string_view"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"Generic recoverable error\"" + }, + "saw-err-recoverable-is_critical": { + "id": "saw-err-recoverable-is_critical", + "name": "is_critical", + "type": ["bool"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "false" + } + } +} diff --git a/docs_oos/data/core/error.json b/docs_oos/data/core/error.json new file mode 100644 index 0000000..8f7a524 --- /dev/null +++ b/docs_oos/data/core/error.json @@ -0,0 +1,168 @@ +{ + "format": 1, + "id": "saw-error", + "kind": "class", + "name": "error", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Exception replacement. Carries a code, a criticality and a message.", + "detailed_description": [ + [ + "The library is written without exceptions, so this takes their place. An error is either recoverable or critical, and the code distinguishes the kind. Additional kinds are added by defining a tag struct with a description and an is_critical flag, which registers itself the first time it is used." + ], + [ + "The code is an index into a process local registry handed out in first use order. Only", + {"name": "no_error", "id": "saw-err-no_error"}, + {"name": "not_found", "id": "saw-err-not_found"}, + "and", + {"name": "out_of_memory", "id": "saw-err-out_of_memory"}, + "are preregistered, so the same error has different codes in two processes. A code must therefore never be sent anywhere; the category string is the portable identity." + ], + [ + "Copying is forbidden on purpose. An error is moved, or copied explicitly through copy_error, so passing one around stays visible at the call site." + ] + ], + "attributes": { + "saw-error-error_code_": { + "id": "saw-error-error_code_", + "name": "error_code_", + "type": ["code"], + "visibility": "private", + "brief_description": "Distinguishes the different error types." + }, + "saw-error-is_critical_": { + "id": "saw-error-is_critical_", + "name": "is_critical_", + "type": ["bool"], + "visibility": "private", + "brief_description": "Kept next to the code so checking doesn't need the registry." + }, + "saw-error-error_message_": { + "id": "saw-error-error_message_", + "name": "error_message_", + "type": ["std::variant< std::string_view, std::string >"], + "visibility": "private", + "brief_description": "A variant for the edge case of being out of memory, where a string cannot be built." + } + }, + "aliases": { + "saw-error-code": { + "id": "saw-error-code", + "name": "code", + "type": ["uint32_t"], + "brief_description": "Type representing the error code." + } + }, + "functions": { + "saw-error-ctor-1": { + "id": "saw-error-ctor-1", + "name": "error", + "type": [], + "parameters": [ + {"name": "id", "type": ["error::code"]}, + {"name": "is_critical", "type": ["bool"]} + ] + }, + "saw-error-ctor-2": { + "id": "saw-error-ctor-2", + "name": "error", + "type": [], + "brief_description": "With a message which outlives the error, such as a literal.", + "parameters": [ + {"name": "id", "type": ["error::code"]}, + {"name": "is_critical", "type": ["bool"]}, + {"name": "msg", "type": ["const std::string_view &"]} + ] + }, + "saw-error-ctor-3": { + "id": "saw-error-ctor-3", + "name": "error", + "type": [], + "brief_description": "With an owned message, for text built at the point of failure.", + "parameters": [ + {"name": "id", "type": ["error::code"]}, + {"name": "is_critical", "type": ["bool"]}, + {"name": "msg", "type": ["std::string &&"]} + ] + }, + "saw-error-get_message": { + "id": "saw-error-get_message", + "name": "get_message", + "type": ["const std::string_view"], + "const": true, + "brief_description": "Returns a string view to the message." + }, + "saw-error-get_category": { + "id": "saw-error-get_category", + "name": "get_category", + "type": ["const std::string_view"], + "const": true, + "brief_description": "Returns a view describing which error this is.", + "detailed_description": [ + ["Looked up in the registry. This, not the code, is the identity which means the same thing in another process."] + ] + }, + "saw-error-failed": { + "id": "saw-error-failed", + "name": "failed", + "type": ["bool"], + "const": true, + "brief_description": "Checks if it is an error at all, since the code zero is reserved for no error." + }, + "saw-error-is_critical": { + "id": "saw-error-is_critical", + "name": "is_critical", + "type": ["bool"], + "const": true, + "brief_description": "Checks if the error is critical." + }, + "saw-error-is_recoverable": { + "id": "saw-error-is_recoverable", + "name": "is_recoverable", + "type": ["bool"], + "const": true, + "brief_description": "Checks if the error is recoverable." + }, + "saw-error-copy_error": { + "id": "saw-error-copy_error", + "name": "copy_error", + "type": ["error"], + "const": true, + "brief_description": "Replaces the copy constructor, so copying an error is always explicit.", + "detailed_description": [ + ["If copying the message runs out of memory, the copy keeps the code and gets a static message instead of failing."] + ] + }, + "saw-error-get_id": { + "id": "saw-error-get_id", + "name": "get_id", + "type": ["error::code"], + "const": true, + "brief_description": "Returns the code." + }, + "saw-error-is_type": { + "id": "saw-error-is_type", + "name": "is_type", + "type": ["bool"], + "const": true, + "brief_description": "Checks whether this error is of a given kind.", + "detailed_description": [ + ["The way to branch on an error. Comparing codes directly only works inside one process."] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "An error tag struct, e.g. err::not_found."} + ], + "examples": [ + { + "title": "Branching on the kind of failure", + "language": "cpp", + "code": "auto eov = srv.receive(dat_id);\nif(eov.is_error()){\n\tauto& err = eov.get_error();\n\tif(err.is_type()){\n\t\t/// Nothing stored under that id yet.\n\t\treturn make_void();\n\t}\n\treturn std::move(err);\n}\n" + } + ] + } + }, + "notes": [ + "Copy is forbidden; use copy_error when a second instance is genuinely needed." + ] +} diff --git a/docs_oos/data/core/error_builder.json b/docs_oos/data/core/error_builder.json new file mode 100644 index 0000000..4385514 --- /dev/null +++ b/docs_oos/data/core/error_builder.json @@ -0,0 +1,65 @@ +{ + "format": 1, + "id": "saw-error_builder", + "kind": "struct", + "name": "error_builder", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Builds an error message lazily, only when the error is actually created.", + "detailed_description": [ + [ + "Composing a message costs an allocation and some string work, which is wasted on the path where nothing fails. The builder holds a callable instead and runs it at the moment the error is made." + ], + [ + "If building the message throws, the error is still produced with the generic message passed in, so an out of memory situation cannot turn a failure into a crash." + ] + ], + "attributes": { + "saw-error_builder-func_": { + "id": "saw-error_builder-func_", + "name": "func_", + "type": ["std::function< std::string() >"], + "visibility": "private" + } + }, + "functions": { + "saw-error_builder-ctor": { + "id": "saw-error_builder-ctor", + "name": "error_builder", + "type": [], + "templates": [ + {"name": "Func", "kind": "type", "brief_description": "Callable returning the message."} + ], + "parameters": [ + {"name": "func__", "type": ["Func &&"]} + ] + }, + "saw-error_builder-make_error": { + "id": "saw-error_builder-make_error", + "name": "make_error", + "type": [{"name": "error", "id": "saw-error"}], + "brief_description": "Runs the callable and produces the error.", + "detailed_description": [ + ["The callable is cleared afterwards, so a builder yields its message once."] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "The error tag struct to produce."} + ], + "parameters": [ + { + "name": "generic", + "type": ["const std::string_view &"], + "brief_description": "Fallback message if building the real one fails." + } + ], + "examples": [ + { + "title": "A message which is only built on failure", + "language": "cpp", + "code": "return build_error([&](){\n\treturn std::string{\"Expect ',' or '}', but got \"}\n\t\t+ std::string{static_cast(buff.read())};\n}).make_error(\"Struct separator expected\");\n" + } + ] + } + } +} diff --git a/docs_oos/data/core/error_or.json b/docs_oos/data/core/error_or.json new file mode 100644 index 0000000..a4a0d3b --- /dev/null +++ b/docs_oos/data/core/error_or.json @@ -0,0 +1,110 @@ +{ + "format": 1, + "id": "saw-error_or", + "kind": "class", + "name": "error_or", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Holds either a value or an error.", + "detailed_description": [ + [ + "The return type of nearly everything which can fail. It is a variant of an", + {"name": "error", "id": "saw-error"}, + "and the value, with void represented by an internal empty type so error_or< void > works like any other." + ], + [ + "get_value and get_error return references into the object, so the error_or itself has to stay alive while the reference is used. Chaining the two, as in f().get_value(), hands back a reference into a temporary." + ], + [ + "The default constructor exists but fills in an invalid_state error, so a default constructed one is already failed rather than empty. The value type therefore does not have to be default constructible." + ] + ], + "bases": [ + [{"name": "error_or_value", "id": "saw-error_or_value"}] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "The value type. May be void."} + ], + "attributes": { + "saw-error_or-value_or_error_": { + "id": "saw-error_or-value_or_error_", + "name": "value_or_error_", + "type": ["std::variant< error, fix_void< T > >"], + "visibility": "private" + } + }, + "functions": { + "saw-error_or-ctor-1": { + "id": "saw-error_or-ctor-1", + "name": "error_or", + "type": [], + "brief_description": "Default constructs to an invalid_state error, not to a value." + }, + "saw-error_or-ctor-2": { + "id": "saw-error_or-ctor-2", + "name": "error_or", + "type": [], + "brief_description": "From a value. Implicit, so a function can return the value directly.", + "parameters": [ + {"name": "value", "type": ["const fix_void< T > &"]} + ] + }, + "saw-error_or-ctor-3": { + "id": "saw-error_or-ctor-3", + "name": "error_or", + "type": [], + "brief_description": "From an error. Implicit, so a function can return make_error directly.", + "parameters": [ + {"name": "error", "type": ["error &&"]} + ] + }, + "saw-error_or-is_value": { + "id": "saw-error_or-is_value", + "name": "is_value", + "type": ["bool"], + "const": true, + "brief_description": "True if it holds the value." + }, + "saw-error_or-is_error": { + "id": "saw-error_or-is_error", + "name": "is_error", + "type": ["bool"], + "const": true, + "brief_description": "True if it holds an error." + }, + "saw-error_or-get_value": { + "id": "saw-error_or-get_value", + "name": "get_value", + "type": ["fix_void< T > &"], + "brief_description": "The value. Only valid if is_value." + }, + "saw-error_or-get_error": { + "id": "saw-error_or-get_error", + "name": "get_error", + "type": ["error &"], + "brief_description": "The error. Only valid if is_error." + } + }, + "specializations": [ + { + "name": "error_or< error_or< T > >", + "id": "saw-error_or-nested", + "brief_description": "Deleted. Guards against an error_or which wraps another one." + } + ], + "examples": [ + { + "title": "Passing a failure upwards", + "description": [ + [ + "The shape repeated throughout the codebase. The error is moved out, because", + {"name": "error", "id": "saw-error"}, + "forbids copying." + ] + ], + "language": "cpp", + "code": "error_or> load(id dat_id){\n\tauto eov = srv.receive(dat_id);\n\tif(eov.is_error()){\n\t\treturn std::move(eov.get_error());\n\t}\n\n\treturn std::move(eov.get_value());\n}\n" + } + ] +} diff --git a/docs_oos/data/core/error_or.nested.json b/docs_oos/data/core/error_or.nested.json new file mode 100644 index 0000000..34bd2b5 --- /dev/null +++ b/docs_oos/data/core/error_or.nested.json @@ -0,0 +1,24 @@ +{ + "format": 1, + "id": "saw-error_or-nested", + "kind": "class", + "name": "error_or", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/error.hpp", + "is_special": true, + "specializes": "saw-error_or", + "arguments": ["error_or< T >"], + "brief_description": "Type safe guard against an error_or holding another error_or.", + "detailed_description": [ + [ + "Its only member is a deleted default constructor, so the type cannot be formed. It catches the case where an error_or is returned from something which already returns one, which is easy to do by accident once calls are nested a few levels deep." + ], + [ + "The failure then happens where the type is written instead of somewhere further down in a confusing overload." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ] +} diff --git a/docs_oos/data/core/error_or_value.json b/docs_oos/data/core/error_or_value.json new file mode 100644 index 0000000..1b93ee9 --- /dev/null +++ b/docs_oos/data/core/error_or_value.json @@ -0,0 +1,26 @@ +{ + "format": 1, + "id": "saw-error_or_value", + "kind": "class", + "name": "error_or_value", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/error.hpp", + "brief_description": "Type erased base of every error_or.", + "detailed_description": [ + [ + "Lets code hold a result whose value type it doesn't know, and recover it later with as. The cast is unchecked, so the caller has to know which type it stored." + ] + ], + "functions": { + "saw-error_or_value-as": { + "id": "saw-error_or_value-as", + "name": "as", + "type": [{"name": "error_or", "id": "saw-error_or"}, "< unfix_void< T > > &"], + "brief_description": "Recovers the concrete result.", + "templates": [ + {"name": "T", "kind": "type", "brief_description": "The value type which was stored."} + ] + } + } +} diff --git a/docs_oos/data/core/heap.json b/docs_oos/data/core/heap.json new file mode 100644 index 0000000..6500895 --- /dev/null +++ b/docs_oos/data/core/heap.json @@ -0,0 +1,23 @@ +{ + "format": 1, + "id": "saw-heap", + "kind": "function", + "name": "heap", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": [{"name": "own", "id": "saw-own"}, "< T >"], + "brief_description": "Constructs an object on the heap and hands back sole ownership.", + "detailed_description": [ + [ + "The one place new is called. Arguments are forwarded to the constructor, so a type which forbids copying and moving can still be built here, which is exactly what the registered servers rely on." + ] + ], + "templates": [ + {"name": "T", "kind": "type"}, + {"name": "Args", "kind": "type", "pack": true} + ], + "parameters": [ + {"name": "args", "type": ["Args &&..."], "brief_description": "Forwarded to the constructor of T."} + ] +} diff --git a/docs_oos/data/core/id.json b/docs_oos/data/core/id.json new file mode 100644 index 0000000..dc22fac --- /dev/null +++ b/docs_oos/data/core/id.json @@ -0,0 +1,67 @@ +{ + "format": 1, + "id": "saw-id", + "kind": "class", + "name": "id", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/id.hpp", + "brief_description": "An identifier tied to the class it stands for.", + "detailed_description": [ + [ + "A number underneath, but a distinct type per subject, so an id for one schema cannot be handed where an id for another is expected. That is what makes the remote layer safe to work with: nothing there moves data, it moves these." + ], + [ + "Comparable and copyable, with no default constructor, so an id always refers to something somebody handed out." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "What the id refers to."} + ], + "attributes": { + "saw-id-value_": { + "id": "saw-id-value_", + "name": "value_", + "type": ["uint64_t"], + "visibility": "private" + } + }, + "functions": { + "saw-id-ctor": { + "id": "saw-id-ctor", + "name": "id", + "type": [], + "parameters": [ + {"name": "val", "type": ["uint64_t"]} + ] + }, + "saw-id-eq": { + "id": "saw-id-eq", + "name": "operator==", + "type": ["bool"], + "const": true, + "parameters": [ + {"name": "rhs", "type": ["const id< T > &"]} + ] + }, + "saw-id-neq": { + "id": "saw-id-neq", + "name": "operator!=", + "type": ["bool"], + "const": true, + "parameters": [ + {"name": "rhs", "type": ["const id< T > &"]} + ] + }, + "saw-id-get_value": { + "id": "saw-id-get_value", + "name": "get_value", + "type": ["const uint64_t &"], + "const": true, + "brief_description": "The underlying number.", + "detailed_description": [ + ["Mostly for internal purposes, and for the moment an id has to be put somewhere which only understands numbers."] + ] + } + } +} diff --git a/docs_oos/data/core/lent.json b/docs_oos/data/core/lent.json new file mode 100644 index 0000000..06a6751 --- /dev/null +++ b/docs_oos/data/core/lent.json @@ -0,0 +1,21 @@ +{ + "format": 1, + "id": "saw-lent", + "kind": "alias", + "name": "lent", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": ["std::weak_ptr< T >"], + "brief_description": "A borrow of a shared object which does not keep it alive.", + "detailed_description": [ + [ + "The counterpart of", + {"name": "our", "id": "saw-our"}, + "for a party which wants access but must not extend the lifetime, which is how cycles between the two are avoided." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ] +} diff --git a/docs_oos/data/core/maybe.json b/docs_oos/data/core/maybe.json new file mode 100644 index 0000000..82ff6a0 --- /dev/null +++ b/docs_oos/data/core/maybe.json @@ -0,0 +1,21 @@ +{ + "format": 1, + "id": "saw-maybe", + "kind": "alias", + "name": "maybe", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": ["std::optional< T >"], + "brief_description": "A value which may be absent, without that absence being a failure.", + "detailed_description": [ + [ + "Distinct from", + {"name": "error_or", "id": "saw-error_or"}, + "which says something went wrong. A maybe says a value is legitimately not there, as with an optional response slot where the caller may or may not have picked one." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ] +} diff --git a/docs_oos/data/core/our.json b/docs_oos/data/core/our.json new file mode 100644 index 0000000..e1ab459 --- /dev/null +++ b/docs_oos/data/core/our.json @@ -0,0 +1,24 @@ +{ + "format": 1, + "id": "saw-our", + "kind": "alias", + "name": "our", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": ["std::shared_ptr< T >"], + "brief_description": "Shared ownership of a heap object.", + "detailed_description": [ + [ + "Used where several parties genuinely keep something alive, such as a device handle held by both a server and the data allocated on it. Where one owner is enough, prefer", + {"name": "own", "id": "saw-own"} + ], + [ + "Created through", + {"name": "share", "id": "saw-share"} + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ] +} diff --git a/docs_oos/data/core/own.json b/docs_oos/data/core/own.json new file mode 100644 index 0000000..1716ab3 --- /dev/null +++ b/docs_oos/data/core/own.json @@ -0,0 +1,30 @@ +{ + "format": 1, + "id": "saw-own", + "kind": "alias", + "name": "own", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": ["std::unique_ptr< T >"], + "brief_description": "Sole ownership of a heap object.", + "detailed_description": [ + [ + "One of the four ownership words the codebase uses in place of raw pointers: own is sole ownership,", + {"name": "our", "id": "saw-our"}, + "is shared,", + {"name": "lent", "id": "saw-lent"}, + "is a weak borrow, and", + {"name": "ptr", "id": "saw-ptr"}, + "owns nothing at all." + ], + [ + "Created through", + {"name": "heap", "id": "saw-heap"}, + "rather than by calling new." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ] +} diff --git a/docs_oos/data/core/parameter_key_pack_index.json b/docs_oos/data/core/parameter_key_pack_index.json new file mode 100644 index 0000000..1d88931 --- /dev/null +++ b/docs_oos/data/core/parameter_key_pack_index.json @@ -0,0 +1,35 @@ +{ + "format": 1, + "id": "saw-parameter_key_pack_index", + "kind": "struct", + "name": "parameter_key_pack_index", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Returns the position of a name in a pack of string literals.", + "detailed_description": [ + [ + "What turns a written name into an index. Looking a struct member up by its name, or an interface function by the literal handed to call, goes through this and then through", + {"name": "parameter_pack_type", "id": "saw-parameter_pack_type"}, + "to reach the type sitting at the same position." + ], + [ + "A name which is not in the pack is a compile error, which is why a misspelled member name fails at the call site." + ] + ], + "templates": [ + {"name": "V", "kind": "non_type", "type": "string_literal", "brief_description": "The name being looked for."}, + {"name": "Keys", "kind": "non_type", "type": "string_literal", "pack": true} + ], + "attributes": { + "saw-parameter_key_pack_index-value": { + "id": "saw-parameter_key_pack_index-value", + "name": "value", + "type": ["uint64_t"], + "visibility": "public", + "static": true, + "constexpr": true, + "brief_description": "Zero based position of the name." + } + } +} diff --git a/docs_oos/data/core/parameter_key_pack_type.json b/docs_oos/data/core/parameter_key_pack_type.json new file mode 100644 index 0000000..bd3041f --- /dev/null +++ b/docs_oos/data/core/parameter_key_pack_type.json @@ -0,0 +1,32 @@ +{ + "format": 1, + "id": "saw-parameter_key_pack_type", + "kind": "struct", + "name": "parameter_key_pack_type", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Returns the name at a position in a pack of string literals.", + "detailed_description": [ + [ + "The inverse of", + {"name": "parameter_key_pack_index", "id": "saw-parameter_key_pack_index"}, + "and the piece which makes compile time loops over named members possible: at index i it yields the literal, which can then be used as a template argument again." + ] + ], + "templates": [ + {"name": "i", "kind": "non_type", "type": "uint64_t", "brief_description": "Zero based position."}, + {"name": "Keys", "kind": "non_type", "type": "string_literal", "pack": true} + ], + "attributes": { + "saw-parameter_key_pack_type-literal": { + "id": "saw-parameter_key_pack_type-literal", + "name": "literal", + "type": [{"name": "string_literal", "id": "saw-string_literal"}], + "visibility": "public", + "static": true, + "constexpr": true, + "brief_description": "The name at that position." + } + } +} diff --git a/docs_oos/data/core/parameter_pack_index.json b/docs_oos/data/core/parameter_pack_index.json new file mode 100644 index 0000000..a553e31 --- /dev/null +++ b/docs_oos/data/core/parameter_pack_index.json @@ -0,0 +1,32 @@ +{ + "format": 1, + "id": "saw-parameter_pack_index", + "kind": "struct", + "name": "parameter_pack_index", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Returns the position of a type in a parameter pack.", + "detailed_description": [ + [ + "The inverse of", + {"name": "parameter_pack_type", "id": "saw-parameter_pack_type"}, + "Recurses until the head matches, so a type which is not in the pack fails to compile rather than yielding a wrong index." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "The type being looked for."}, + {"name": "TL", "kind": "type", "pack": true, "brief_description": "The pack to search."} + ], + "attributes": { + "saw-parameter_pack_index-value": { + "id": "saw-parameter_pack_index-value", + "name": "value", + "type": ["size_t"], + "visibility": "public", + "static": true, + "constexpr": true, + "brief_description": "Zero based position of T in the pack." + } + } +} diff --git a/docs_oos/data/core/parameter_pack_type.json b/docs_oos/data/core/parameter_pack_type.json new file mode 100644 index 0000000..2175cdd --- /dev/null +++ b/docs_oos/data/core/parameter_pack_type.json @@ -0,0 +1,27 @@ +{ + "format": 1, + "id": "saw-parameter_pack_type", + "kind": "struct", + "name": "parameter_pack_type", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Returns the type at a position in a parameter pack.", + "detailed_description": [ + [ + "The workhorse of every compile time loop in this codebase. Recursion over an index plus this is how a struct, a tuple or an interface is walked member by member, since a pack cannot be indexed directly." + ] + ], + "templates": [ + {"name": "N", "kind": "non_type", "type": "size_t", "brief_description": "Zero based position."}, + {"name": "T", "kind": "type", "pack": true} + ], + "aliases": { + "saw-parameter_pack_type-type": { + "id": "saw-parameter_pack_type-type", + "name": "type", + "type": ["the Nth type of T..."], + "brief_description": "The type at that position." + } + } +} diff --git a/docs_oos/data/core/parameter_pack_value.json b/docs_oos/data/core/parameter_pack_value.json new file mode 100644 index 0000000..920bd09 --- /dev/null +++ b/docs_oos/data/core/parameter_pack_value.json @@ -0,0 +1,33 @@ +{ + "format": 1, + "id": "saw-parameter_pack_value", + "kind": "struct", + "name": "parameter_pack_value", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Returns the value at a position in a value pack.", + "detailed_description": [ + [ + "The value counterpart of", + {"name": "parameter_pack_type", "id": "saw-parameter_pack_type"}, + "used where a pack of numbers has to be indexed, such as the dimensions of a fixed size array." + ] + ], + "templates": [ + {"name": "i", "kind": "non_type", "type": "uint64_t", "brief_description": "Zero based position."}, + {"name": "T", "kind": "type", "brief_description": "Type of the values."}, + {"name": "V", "kind": "non_type", "type": "T", "pack": true} + ], + "attributes": { + "saw-parameter_pack_value-value": { + "id": "saw-parameter_pack_value-value", + "name": "value", + "type": ["T"], + "visibility": "public", + "static": true, + "constexpr": true, + "brief_description": "The value at that position." + } + } +} diff --git a/docs_oos/data/core/ptr.json b/docs_oos/data/core/ptr.json new file mode 100644 index 0000000..50fea1a --- /dev/null +++ b/docs_oos/data/core/ptr.json @@ -0,0 +1,64 @@ +{ + "format": 1, + "id": "saw-ptr", + "kind": "class", + "name": "ptr", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "brief_description": "Non owning pointer which may be empty.", + "detailed_description": [ + [ + "States in the type system that something is referred to but not owned. Copyable and reassignable, unlike", + {"name": "ref", "id": "saw-ref"}, + "and checkable, unlike a reference." + ], + [ + "Dereferencing goes through the call operator rather than through star or arrow, which keeps the indirection visible at every use." + ], + [ + "Nothing here tracks lifetime. A ptr outliving its target is a bug the type cannot catch, which is why the classes holding one, such as the data servers, forbid moving themselves." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ], + "attributes": { + "saw-ptr-ptr_": { + "id": "saw-ptr-ptr_", + "name": "ptr_", + "type": ["T *"], + "visibility": "private" + } + }, + "functions": { + "saw-ptr-ctor-1": { + "id": "saw-ptr-ctor-1", + "name": "ptr", + "type": [], + "brief_description": "Empty." + }, + "saw-ptr-ctor-2": { + "id": "saw-ptr-ctor-2", + "name": "ptr", + "type": [], + "brief_description": "Pointing at an object. Implicit, so passing an object where a ptr is expected just works.", + "parameters": [ + {"name": "ptr__", "type": ["T &"]} + ] + }, + "saw-ptr-call": { + "id": "saw-ptr-call", + "name": "operator()", + "type": ["T &"], + "brief_description": "The pointed at object. Undefined if empty." + }, + "saw-ptr-is_valid": { + "id": "saw-ptr-is_valid", + "name": "is_valid", + "type": ["bool"], + "const": true, + "brief_description": "Whether it points at anything." + } + } +} diff --git a/docs_oos/data/core/ref.json b/docs_oos/data/core/ref.json new file mode 100644 index 0000000..518a5d6 --- /dev/null +++ b/docs_oos/data/core/ref.json @@ -0,0 +1,47 @@ +{ + "format": 1, + "id": "saw-ref", + "kind": "class", + "name": "ref", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "brief_description": "Reference class for easier distinction of references and their referenced types.", + "detailed_description": [ + [ + "Always refers to something, so unlike", + {"name": "ptr", "id": "saw-ptr"}, + "it has no empty state and no validity check." + ], + [ + "Moving is forbidden, since that would invalidate the type, while copying is allowed. It is constexpr throughout, so it can be formed and followed at compile time." + ] + ], + "templates": [ + {"name": "T", "kind": "type"} + ], + "attributes": { + "saw-ref-ref_": { + "id": "saw-ref-ref_", + "name": "ref_", + "type": ["T *"], + "visibility": "private" + } + }, + "functions": { + "saw-ref-ctor": { + "id": "saw-ref-ctor", + "name": "ref", + "type": [], + "parameters": [ + {"name": "ref__", "type": ["T &"]} + ] + }, + "saw-ref-call": { + "id": "saw-ref-call", + "name": "operator()", + "type": ["T &"], + "brief_description": "The referenced object." + } + } +} diff --git a/docs_oos/data/core/ring_buffer.json b/docs_oos/data/core/ring_buffer.json new file mode 100644 index 0000000..eb6a0d0 --- /dev/null +++ b/docs_oos/data/core/ring_buffer.json @@ -0,0 +1,55 @@ +{ + "format": 1, + "id": "saw-ring_buffer", + "kind": "class", + "name": "ring_buffer", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/buffer.hpp", + "brief_description": "Buffer wrapping around if the read cursor caught up.", + "detailed_description": [ + [ + "Fixed capacity, reused in place. Suited to a stream where bytes are produced and consumed continuously, since nothing is allocated after construction." + ], + [ + "The capacity does not grow, so a write beyond what the reader has freed fails with", + {"name": "buffer_exhausted", "id": "saw-err-buffer_exhausted"}, + "rather than resizing." + ] + ], + "bases": [ + [{"name": "buffer", "id": "saw-buffer"}] + ], + "attributes": { + "saw-ring_buffer-write_reached_read_": { + "id": "saw-ring_buffer-write_reached_read_", + "name": "write_reached_read_", + "type": ["bool"], + "visibility": "private", + "brief_description": "Distinguishes a full buffer from an empty one, since both have equal cursors." + } + }, + "functions": { + "saw-ring_buffer-ctor-1": { + "id": "saw-ring_buffer-ctor-1", + "name": "ring_buffer", + "type": [], + "brief_description": "With the default capacity of RING_BUFFER_MAX_SIZE bytes." + }, + "saw-ring_buffer-ctor-2": { + "id": "saw-ring_buffer-ctor-2", + "name": "ring_buffer", + "type": [], + "parameters": [ + {"name": "size", "type": ["size_t"]} + ] + }, + "saw-ring_buffer-size": { + "id": "saw-ring_buffer-size", + "name": "size", + "type": ["size_t"], + "const": true, + "brief_description": "Total capacity, not the amount currently held." + } + } +} diff --git a/docs_oos/data/core/share.json b/docs_oos/data/core/share.json new file mode 100644 index 0000000..4d1df1f --- /dev/null +++ b/docs_oos/data/core/share.json @@ -0,0 +1,25 @@ +{ + "format": 1, + "id": "saw-share", + "kind": "function", + "name": "share", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "type": [{"name": "our", "id": "saw-our"}, "< T >"], + "brief_description": "Constructs an object on the heap under shared ownership.", + "detailed_description": [ + [ + "The counterpart of", + {"name": "heap", "id": "saw-heap"}, + "for the cases where ownership is genuinely shared." + ] + ], + "templates": [ + {"name": "T", "kind": "type"}, + {"name": "Args", "kind": "type", "pack": true} + ], + "parameters": [ + {"name": "args", "type": ["Args &&..."], "brief_description": "Forwarded to the constructor of T."} + ] +} diff --git a/docs_oos/data/core/string_literal.json b/docs_oos/data/core/string_literal.json new file mode 100644 index 0000000..4bd6e9b --- /dev/null +++ b/docs_oos/data/core/string_literal.json @@ -0,0 +1,74 @@ +{ + "format": 1, + "id": "saw-string_literal", + "kind": "class", + "name": "string_literal", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/string_literal.hpp", + "brief_description": "Helper object which turns a string literal into a template parameter.", + "detailed_description": [ + [ + "It guarantees compile time uniqueness and thus allows using strings in template parameters. Everything in this codebase which is addressed by name rests on it: struct members, interface functions, and the schema hashes derived from them." + ], + [ + "Because the length is part of the type, two literals of different length are different types, and comparing them is a compile time false rather than an error." + ] + ], + "templates": [ + {"name": "CharT", "kind": "type"}, + {"name": "N", "kind": "non_type", "type": "size_t", "brief_description": "Length including the null terminator."} + ], + "attributes": { + "saw-string_literal-data": { + "id": "saw-string_literal-data", + "name": "data", + "type": ["std::array< CharT, N >"], + "visibility": "public" + } + }, + "functions": { + "saw-string_literal-ctor": { + "id": "saw-string_literal-ctor", + "name": "string_literal", + "type": [], + "brief_description": "From a literal. Copies it character by character so the whole thing is constexpr.", + "parameters": [ + {"name": "input", "type": ["const CharT (&)[N]"]} + ] + }, + "saw-string_literal-view": { + "id": "saw-string_literal-view", + "name": "view", + "type": ["std::string_view"], + "const": true, + "brief_description": "The literal as a view, for the places which compare against runtime strings." + }, + "saw-string_literal-eq": { + "id": "saw-string_literal-eq", + "name": "operator==", + "type": ["bool"], + "const": true, + "brief_description": "Equality. A literal of different length is never equal.", + "parameters": [ + {"name": "rhs", "type": ["const string_literal< CharTR, NR > &"]} + ] + }, + "saw-string_literal-plus": { + "id": "saw-string_literal-plus", + "name": "operator+", + "type": ["string_literal< CharT, N+NR-1 >"], + "const": true, + "brief_description": "Concatenation, dropping the null terminator of the left side.", + "templates": [ + {"name": "NR", "kind": "non_type", "type": "size_t"} + ], + "parameters": [ + {"name": "rhs", "type": ["const string_literal< CharT, NR > &"]} + ] + } + }, + "notes": [ + "The literal operator \"\"_sl builds one from a quoted string." + ] +} diff --git a/docs_oos/data/core/tmpl_concat.json b/docs_oos/data/core/tmpl_concat.json new file mode 100644 index 0000000..8260faa --- /dev/null +++ b/docs_oos/data/core/tmpl_concat.json @@ -0,0 +1,34 @@ +{ + "format": 1, + "id": "saw-tmpl_concat", + "kind": "struct", + "name": "tmpl_concat", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "Concats two groups into one.", + "detailed_description": [ + [ + "Declared only; the work happens in the specializations, one for", + {"name": "tmpl_group", "id": "saw-tmpl_group"}, + "and one for", + {"name": "tmpl_value_group", "id": "saw-tmpl_value_group"}, + "so concatenating anything else is a compile error rather than a surprise." + ], + [ + "The value groups have to agree on their value type, which the specialization enforces by binding it once for both sides." + ] + ], + "templates": [ + {"name": "T", "kind": "type"}, + {"name": "U", "kind": "type"} + ], + "aliases": { + "saw-tmpl_concat-type": { + "id": "saw-tmpl_concat-type", + "name": "type", + "type": ["tmpl_group< T..., U... >"], + "brief_description": "The joined group. Only present on the specializations." + } + } +} diff --git a/docs_oos/data/core/tmpl_group.json b/docs_oos/data/core/tmpl_group.json new file mode 100644 index 0000000..c999492 --- /dev/null +++ b/docs_oos/data/core/tmpl_group.json @@ -0,0 +1,39 @@ +{ + "format": 1, + "id": "saw-tmpl_group", + "kind": "struct", + "name": "tmpl_group", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "A list of types, carried as a type.", + "detailed_description": [ + [ + "Lets a pack be passed around, stored in an alias and handed to another template, which a bare parameter pack cannot. The remote layer uses one to name every schema an interface mentions, and then maps it to a tuple of servers." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "pack": true} + ], + "attributes": { + "saw-tmpl_group-name": { + "id": "saw-tmpl_group-name", + "name": "name", + "type": [{"name": "string_literal", "id": "saw-string_literal"}], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"tmpl_group\"", + "brief_description": "Used when hashing a group." + }, + "saw-tmpl_group-size": { + "id": "saw-tmpl_group-size", + "name": "size", + "type": ["uint64_t"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "sizeof...(T)" + } + } +} diff --git a/docs_oos/data/core/tmpl_reduce.json b/docs_oos/data/core/tmpl_reduce.json new file mode 100644 index 0000000..495738d --- /dev/null +++ b/docs_oos/data/core/tmpl_reduce.json @@ -0,0 +1,31 @@ +{ + "format": 1, + "id": "saw-tmpl_reduce", + "kind": "struct", + "name": "tmpl_reduce", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/reduce_templates.hpp", + "brief_description": "Removes duplicate types from a group.", + "detailed_description": [ + [ + "Turns a", + {"name": "tmpl_group", "id": "saw-tmpl_group"}, + "into one where every type appears once. The remote layer needs it because an interface mentions a schema once per function, while there must be exactly one data server per schema." + ], + [ + "It is also what makes the tuple lookups work: fetching an element by type requires that type to occur exactly once." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "The group to reduce."} + ], + "aliases": { + "saw-tmpl_reduce-type": { + "id": "saw-tmpl_reduce-type", + "name": "type", + "type": ["typename impl::tmpl_group_reduce< T >::reduced_type"], + "brief_description": "The group without duplicates." + } + } +} diff --git a/docs_oos/data/core/tmpl_value_group.json b/docs_oos/data/core/tmpl_value_group.json new file mode 100644 index 0000000..0ebff2c --- /dev/null +++ b/docs_oos/data/core/tmpl_value_group.json @@ -0,0 +1,41 @@ +{ + "format": 1, + "id": "saw-tmpl_value_group", + "kind": "struct", + "name": "tmpl_value_group", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/templates.hpp", + "brief_description": "A list of values of one type, carried as a type.", + "detailed_description": [ + [ + "The value counterpart of", + {"name": "tmpl_group", "id": "saw-tmpl_group"}, + "for packs of numbers such as array dimensions." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "Type of the values."}, + {"name": "values", "kind": "non_type", "type": "T", "pack": true} + ], + "attributes": { + "saw-tmpl_value_group-name": { + "id": "saw-tmpl_value_group-name", + "name": "name", + "type": [{"name": "string_literal", "id": "saw-string_literal"}], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "\"tmpl_value_group\"" + }, + "saw-tmpl_value_group-size": { + "id": "saw-tmpl_value_group-size", + "name": "size", + "type": ["uint64_t"], + "visibility": "public", + "static": true, + "constexpr": true, + "initializer": "sizeof...(values)" + } + } +} diff --git a/docs_oos/data/core/tree.json b/docs_oos/data/core/tree.json new file mode 100644 index 0000000..3236859 --- /dev/null +++ b/docs_oos/data/core/tree.json @@ -0,0 +1,75 @@ +{ + "format": 1, + "id": "saw-tree", + "kind": "class", + "name": "tree", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/tree.hpp", + "brief_description": "A tree of values, tying the recursive knot.", + "detailed_description": [ + [ + "A thin wrapper over a", + {"name": "tree_container", "id": "saw-tree_container"}, + "whose branches hold this very type. The container and the", + {"name": "branch", "id": "saw-branch"}, + "are written against an open Tree parameter precisely so that this class can close it, which keeps the two of them usable for other node types as well." + ], + [ + "This is the type to reach for; the other two are the machinery underneath." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "Leaf value type."} + ], + "attributes": { + "saw-tree-data_": { + "id": "saw-tree-data_", + "name": "data_", + "type": [{"name": "tree_container", "id": "saw-tree_container"}, "< T, tree< T > >"], + "visibility": "private" + } + }, + "functions": { + "saw-tree-reserve": { + "id": "saw-tree-reserve", + "name": "reserve", + "type": ["error_or< void >"], + "brief_description": "Reserves room for branches up front.", + "parameters": [ + {"name": "size", "type": ["std::size_t"]} + ] + }, + "saw-tree-size": { + "id": "saw-tree-size", + "name": "size", + "type": ["size_t"], + "const": true, + "brief_description": "Number of branches directly below this node." + }, + "saw-tree-add-1": { + "id": "saw-tree-add-1", + "name": "add", + "type": ["error_or< size_t >"], + "brief_description": "Adds a branch holding a sub tree and returns its index." + }, + "saw-tree-add-2": { + "id": "saw-tree-add-2", + "name": "add", + "type": ["error_or< size_t >"], + "brief_description": "Adds a branch holding a leaf and returns its index.", + "parameters": [ + {"name": "leaf", "type": ["T"]} + ] + }, + "saw-tree-at": { + "id": "saw-tree-at", + "name": "at", + "type": [{"name": "branch", "id": "saw-branch"}, "< T, tree< T > > &"], + "brief_description": "The branch at an index.", + "parameters": [ + {"name": "i", "type": ["size_t"]} + ] + } + } +} diff --git a/docs_oos/data/core/tree_container.json b/docs_oos/data/core/tree_container.json new file mode 100644 index 0000000..5f01db8 --- /dev/null +++ b/docs_oos/data/core/tree_container.json @@ -0,0 +1,78 @@ +{ + "format": 1, + "id": "saw-tree_container", + "kind": "class", + "name": "tree_container", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/tree.hpp", + "brief_description": "Tree object holding branches.", + "detailed_description": [ + [ + "The name comes from the fact that a tree acts as a node while the", + {"name": "branch", "id": "saw-branch"}, + "class is the edge to a leaf or to other nodes. A container holds the branches, and each branch either has a leaf or another sub tree." + ], + [ + "Growing is done through add, which reports failure as a value instead of throwing, so a tree can be built in code which must not throw." + ] + ], + "templates": [ + {"name": "T", "kind": "type", "brief_description": "Leaf value type."}, + {"name": "Tree", "kind": "type", "brief_description": "The tree type a branch may hold instead of a leaf."} + ], + "attributes": { + "saw-tree_container-children_": { + "id": "saw-tree_container-children_", + "name": "children_", + "type": ["std::vector<", {"name": "branch", "id": "saw-branch"}, "< T, Tree > >"], + "visibility": "private", + "brief_description": "Object holding the branch instances." + } + }, + "functions": { + "saw-tree_container-reserve": { + "id": "saw-tree_container-reserve", + "name": "reserve", + "type": ["error_or< void >"], + "brief_description": "Reserves room for branches up front.", + "parameters": [ + {"name": "siz", "type": ["std::size_t"]} + ] + }, + "saw-tree_container-add-1": { + "id": "saw-tree_container-add-1", + "name": "add", + "type": ["error_or< std::size_t >"], + "brief_description": "Adds a branch holding a leaf.", + "parameters": [ + {"name": "leaf", "type": ["T"]} + ] + }, + "saw-tree_container-add-2": { + "id": "saw-tree_container-add-2", + "name": "add", + "type": ["error_or< std::size_t >"], + "brief_description": "Adds a branch holding a sub tree." + }, + "saw-tree_container-size": { + "id": "saw-tree_container-size", + "name": "size", + "type": ["std::size_t"], + "const": true, + "brief_description": "Number of branches." + }, + "saw-tree_container-at": { + "id": "saw-tree_container-at", + "name": "at", + "type": [{"name": "branch", "id": "saw-branch"}, "< T, Tree > &"], + "brief_description": "The branch at an index.", + "parameters": [ + {"name": "i", "type": ["std::size_t"]} + ] + } + }, + "notes": [ + "Copy is forbidden, move is allowed." + ] +} diff --git a/docs_oos/data/core/void_t.json b/docs_oos/data/core/void_t.json new file mode 100644 index 0000000..c21bc20 --- /dev/null +++ b/docs_oos/data/core/void_t.json @@ -0,0 +1,20 @@ +{ + "format": 1, + "id": "saw-void_t", + "kind": "struct", + "name": "void_t", + "namespace": "saw", + "module": "core", + "header": "modules/core/c++/common.hpp", + "brief_description": "Struct describing a void type.", + "detailed_description": [ + [ + "An empty type standing in for void where a real type is needed. It is what lets", + {"name": "error_or", "id": "saw-error_or"}, + "< void > hold a variant at all, since a variant cannot have a void alternative." + ], + [ + "The substitution happens in fix_void and is undone by unfix_void, so the stand in stays an implementation detail of the templates rather than something a caller writes. Returning make_void is how a function which succeeded but has nothing to say says so." + ] + ] +} diff --git a/docs_oos/entity.schema.json b/docs_oos/entity.schema.json index 73011a7..de85b95 100644 --- a/docs_oos/entity.schema.json +++ b/docs_oos/entity.schema.json @@ -16,7 +16,7 @@ "description": "Stable identifier. Becomes the rst file name, the label and the :ref: target, so it replaces the doxygen refid. Convention: namespace and name joined by a dash, with a slug for a specialization, e.g. saw-data_server and saw-data_server-loopback." }, "kind": { - "enum": ["class", "struct", "alias", "function", "variable", "enum", "concept", "namespace"] + "enum": ["class", "struct", "alias", "function", "variable", "enum", "concept", "namespace", "macro"] }, "name": { "type": "string", @@ -40,11 +40,25 @@ "detailed_description": { "$ref": "#/$defs/paragraphs" }, + "type": { + "$ref": "#/$defs/type_tuple", + "description": "Only for an alias, variable or function entity: the aliased type, the variable type, or the return type. A class has no type of its own." + }, + "parameters": { + "type": "array", + "description": "Only for a function entity.", + "items": {"$ref": "#/$defs/parameter"} + }, "templates": { "type": "array", "description": "Template parameters. A partial specialization lists the parameters it introduces, not the ones it binds.", "items": {"$ref": "#/$defs/template_parameter"} }, + "bases": { + "type": "array", + "description": "Base classes, for the few places which use inheritance. Entries are type tuples, so a base which is itself documented links.", + "items": {"$ref": "#/$defs/type_tuple"} + }, "is_special": { "type": "boolean", "default": false, @@ -141,6 +155,17 @@ ] } }, + "parameter": { + "type": "object", + "required": ["name", "type"], + "additionalProperties": false, + "properties": { + "name": {"type": "string"}, + "type": {"$ref": "#/$defs/type_tuple"}, + "default": {"type": "string"}, + "brief_description": {"type": "string"} + } + }, "template_parameter": { "type": "object", "required": ["name", "kind"], @@ -224,17 +249,7 @@ }, "parameters": { "type": "array", - "items": { - "type": "object", - "required": ["name", "type"], - "additionalProperties": false, - "properties": { - "name": {"type": "string"}, - "type": {"$ref": "#/$defs/type_tuple"}, - "default": {"type": "string"}, - "brief_description": {"type": "string"} - } - } + "items": {"$ref": "#/$defs/parameter"} }, "visibility": {"enum": ["public", "protected", "private"], "default": "public"}, "static": {"type": "boolean", "default": false}, -- cgit v1.3.1