docs: centralised documentation todos

Author: NickSdot

docs-old/output-api.md

@@ -130,11 +130,3 @@ PHP_OUTPUT_HANDLER_HOOK_IMMUTABLE
 PHP_OUTPUT_HANDLER_HOOK_DISABLE
     the second arg is ignored; marks the output handler as disabled
 ```
-
-## Open questions
-
-- Should the userland API be adjusted and unified?
-
-Many bits of the manual (and very first implementation) do not comply with the
-behaviour of the current (to be obsoleted) code, thus should the manual or the
-behaviour be adjusted?

docs/source/conf.py

@@ -19,6 +19,7 @@
     'sphinx_design',
     'sphinx.ext.autosectionlabel',
 ]
+exclude_patterns = ['**/*TODO.md']
 myst_enable_extensions = [
     'alert',
     'gfm_autolink',

docs/source/core/TODO.md

@@ -0,0 +1,8 @@
+Core TODO
+
+Pages to add:
+
+- Parser and AST: grammar generation, AST representation, compilation boundaries,
+  and important extension points.
+- Virtual Machine: opcode execution, operands, call frames, and VM variants.
+- Object Handlers: handler contracts, object storage, and common ownership traps.

docs/source/core/data-structures/TODO.md

@@ -0,0 +1,4 @@
+Data Structures TODO
+
+- Add a HashTable page covering ownership, iteration, mutation, and common APIs.
+- Expand the zval macro table and document the remaining internal zval types.

docs/source/core/data-structures/reference-counting.md

@@ -144,8 +144,7 @@ they reference each other. This is called a reference cycle.
 PHP implements a cycle collector that detects such cycles and frees values that are only reachable
 through their own references. The cycle collector will record values that may be involved in a
 cycle, and run when this buffer becomes full. It is also possible to invoke it explicitly by calling
-the `gc_collect_cycles()` function. The cycle collectors design is described in the <a
-href="todo">Cycle collector</a> chapter.
+the `gc_collect_cycles()` function.
 
 ## GC flags
 
@@ -171,8 +170,7 @@ again.
 
 The `GC_PERSISTENT` flag indicates that the value was allocated using `malloc`, instead of PHPs
 own allocator. Usually, such values are alive for the entire lifetime of the process, instead of
-being freed at the end of the request. See the <a href="todo">Zend allocator</a> chapter for more
-information.
+being freed at the end of the request.
 
 The `GC_PERSISTENT_LOCAL` flag indicates that a `GC_PERSISTENT` value is only accessible in one
 thread, and is thus still safe to modify. This flag is only used in debug builds to satisfy an

docs/source/core/data-structures/zend_string.md

@@ -21,9 +21,9 @@ struct _zend_string {
 };
 ```
 
-The `gc` field is used for {doc}`./reference-counting`. The `h` field contains a hash value,
-which is used for <a href="todo">hash table</a> lookups. The `len` field stores the length of the string
-in bytes, and the `val` field contains the actual string data.
+The `gc` field is used for {doc}`./reference-counting`. The `h` field contains a hash value, which is
+used for hash table lookups. The `len` field stores the length of the string in bytes, and the `val`
+field contains the actual string data.
 
 You may wonder why the `val` field is declared as `char val[1]`. This is called the [struct
 hack](https://www.geeksforgeeks.org/struct-hack/) in C. It is used to create structs with a flexible size, namely by allowing the last element
@@ -45,7 +45,7 @@ zend_string_release(string);
 `ZSTR_INIT_LITERAL` creates a `zend_string` from a string literal. It is just a wrapper around
 `zend_string_init(char *string, size_t length, bool persistent)` that provides the length of the
 string at compile time. The `persistent` parameter indicates whether the string is allocated using
-`malloc` (`persistent == true`) or `emalloc`, <a href="todo">PHPs custom allocator</a> (`persistent == false`) that is emptied after each request.
+`malloc` (`persistent == true`) or `emalloc`, PHP's custom allocator (`persistent == false`) that is emptied after each request.
 
 When you're done using the string, you must call `zend_string_release`, or the memory will leak.
 `zend_string_release` will automatically call `malloc` or `emalloc`, depending on how the
@@ -104,8 +104,8 @@ use.
 Programs use some strings many times. For example, if your program declares a class called
 `MyClass`, it would be wasteful to allocate a new string `"MyClass"` every time it is referenced
 within your program. Instead, when repeated strings are expected, php-src uses a technique called
-string interning. Essentially, this is just a simple <a href="todo">HashTable</a> where existing interned
-strings are stored. When creating a new interned string, php-src first checks the interned string
+string interning. Essentially, this is just a simple `HashTable` where existing interned strings are
+stored. When creating a new interned string, php-src first checks the interned string
 buffer. If it finds it there, it can return a pointer to the existing string. If it doesn't, it
 allocates a new string and adds it to the buffer.
 

docs/source/core/data-structures/zval.md

@@ -62,8 +62,8 @@ member, but never both at the same time. However, it doesn't know which member i
 Remembering this is our job, and that's exactly what the `IS_*` constants are for.
 
 The top members of `zend_value` mostly mirror the `IS_*` constants, with the exception of
-`counted`. `counted` polymorphically refers to any <a href="todo">reference counted</a> value, including
-strings, arrays, objects, resources and references. `null` and `bool` are missing from
+`counted`. `counted` polymorphically refers to any [reference-counted](reference-counting.md) value,
+including strings, arrays, objects, resources and references. `null` and `bool` are missing from
 `zend_value` because their types are self-contained.
 
 The rest of the fields aren't important for now.
@@ -108,8 +108,8 @@ struct _zval_struct {
 
 `zval.u1` stores the variable type, the given `IS_*` constant, along with some other flags. It's
 definition looks a bit complicated. You can think of the entire field as a 4 byte integer, split
-into 3 parts. `v.type` stores the actual variable type, `v.type_flags` is used for some <a
-href="todo">reference counting</a> flags, and `v.u.extra` is pretty much unused.
+into 3 parts. `v.type` stores the actual variable type, `v.type_flags` is used for some
+[reference-counting](reference-counting.md) flags, and `v.u.extra` is pretty much unused.
 
 `zval.u2` defines some more storage for various contexts that is often unoccupied. It's there
 because the memory would otherwise be wasted due to padding, so we may as well make use of it. We'll
@@ -135,8 +135,6 @@ there's a `_P`-suffixed variant that performs the same operation on a pointer to
 | `ZVAL_COPY_VALUE(t, s)` | Copy one `zval` to another, including type and value.                                   |
 | `ZVAL_COPY(t, s)`       | Same as `ZVAL_COPY_VALUE`, but if the value is reference counted, increase the counter. |
 
-<!-- _todo: There are many more. -->
-
 ## Other zval types
 
 `zval`s are sometimes used internally with types that don't exist in userland.
@@ -153,16 +151,14 @@ there's a `_P`-suffixed variant that performs the same operation on a pointer to
 property/parameter initializers, etc.) before they are evaluated. The evaluation of a constant
 expression is not always possible during compilation, because they may contain references to values
 only available at runtime. Until that evaluation is possible, the constants contain the AST of the
-expression rather than the concrete values. Check the <a href="todo">parser</a> chapter for more information
-on ASTs. When this flag is set, the `zval.value.ast` union member is set accordingly.
+expression rather than the concrete values. When this flag is set, the `zval.value.ast` union member
+is set accordingly.
 
 `IS_INDIRECT` indicates that the `zval.value.zv` member is populated. This field stores a
 pointer to some other `zval`. This type is mainly used in two situations, namely for intermediate
 values between `FETCH` and `ASSIGN` instructions, and for the sharing of variables in the symbol
 table.
 
-<!-- _todo: There are many more. -->
-
 `IS_PTR` is used for pointers to arbitrary data. Most commonly, this type is used internally for
 `HashTable`, as `HashTable` may only store `zval` values. For example, `EG(class_table)`
 represents the class table, which is a hash map of class names to the corresponding
@@ -173,8 +169,7 @@ Otherwise, it is essentially the same as `IS_PTR`. Arbitrary data is accessed th
 `zval.value.ptr`, and casted to the correct type depending on context. If `ptr` stores a class
 or function, the `zval.value.ce` or `zval.value.func` fields may be used, respectively.
 
-`_IS_ERROR` is used as an error value for some <a href="todo">object handlers</a>. It is described in more
-detail in its own chapter.
+`_IS_ERROR` is used as an error value for some object handlers.
 
 ```c
 /* Fake types used only for type hinting.
@@ -192,7 +187,7 @@ detail in its own chapter.
 ```
 
 These flags are never actually stored in `zval.u1`. They are used for type hinting and in the
-<a href="todo">object handler</a> API.
+object handler API.
 
 This only leaves the `zval.value.ww` field. In short, this field is used on 32-bit platforms when
 copying data from one `zval` to another. Normally, `zval.value.counted` is copied as a generic

docs/source/core/memory-management/TODO.md

@@ -0,0 +1,12 @@
+Memory Management TODO
+
+The Reference Counting page contained TODOs for dedicated Cycle Collector and
+Zend Allocator pages; grouping them under Memory Management makes sense. Pages
+to be added:
+
+- Cycle Collector:
+  candidate buffering, collection phases, collectable types, and correct use of
+  GC flags and macros.
+- Zend Allocator:
+  allocator pairing, overflow-safe allocation, request/persistent lifetimes, and
+  relevant arena cleanup.

docs/source/core/output-buffering-TODO.md

@@ -0,0 +1,7 @@
+## Open Questions
+
+- Should the userland API be adjusted and unified?
+
+Many bits of the manual (and very first implementation) do not comply with the
+behaviour of the current (to be obsoleted) code, thus should the manual or the
+behaviour be adjusted?

docs/source/introduction/high-level-overview.md

@@ -96,8 +96,6 @@ Like with tokenization, we use a tool called `Bison` to generate the parser impl
 grammar specification. The grammar lives in the `Zend/zend_language_parser.y` file. Check the
 [Bison documentation](https://www.gnu.org/software/bison/manual/) for details. Luckily, the syntax is quite approachable.
 
-Parsing is described in more detail in its <a href="todo">dedicated chapter</a>.
-
 ## Compilation
 
 Computers don't understand human language, or even programming languages. They only understand
@@ -149,7 +147,7 @@ With these simple rules, we can see that the interpreter will `echo` only when `
 truthy, and skip over the `echo` otherwise.
 
 That's it! This is how PHP works, fundamentally. Of course, we skipped over a ton of details. The VM
-is quite complex, and will be discussed separately in the <a href="todo">virtual machine</a> chapter.
+is quite complex.
 
 ## Opcache