feat: Unified Docs

README.md

@@ -14,6 +14,219 @@ make html
 
 The output lands in `docs/build/html/`.
 
+## API Authoring Requirements
+
+The API `.rst` files are used by Codea as structured editor metadata, not only as
+rendered documentation. The `luadoc` build emits JSON that Codea consumes for
+Reference, autocomplete, syntax highlighting, and editor affordances.
+
+### Module Namespacing
+
+Use Sphinx's Lua module context as the source of truth for namespacing.
+
+```rst
+.. lua:module:: pasteboard
+
+.. lua:attribute:: name: string
+```
+
+This emits `name` with `module: "pasteboard"`, so Codea treats the symbol as
+`pasteboard.name`. Reference UI should display the qualified name for module
+members.
+
+Rules:
+
+- Use `.. lua:module:: name` once when introducing and documenting a module.
+- Use `.. lua:currentmodule:: name` to return to an existing module context
+  without creating another module entry.
+- Use `.. lua:currentmodule:: None` before globals in a file that previously set
+  a module context.
+- Do not rely on section headings to imply namespacing. The current Lua module
+  context is the authoritative signal.
+
+For mixed files, be explicit:
+
+```rst
+.. lua:module:: style
+
+.. lua:function:: fill(<color>)
+
+Constants
+*********
+
+.. lua:currentmodule:: None
+
+.. lua:attribute:: LEFT: const
+
+.. lua:currentmodule:: style
+
+.. lua:function:: textAlign(align)
+```
+
+Here `style.fill` is namespaced, `LEFT` is global, and later functions return to
+the `style` namespace.
+
+### Structural Table Return Types
+
+Use `:rtype: table$private.<name>` when a function returns a generic Lua table
+but Codea should understand the specific fields of that returned table for
+tooling. Text before `$` is the documentation-facing type. Text after `$` is the
+lookup type. `private.<name>` is module-relative, so inside an `objc` module it
+becomes `objc.private.<name>` in Codea's JSON.
+
+```rst
+.. lua:module:: objc
+
+.. lua:function:: insets(top, left, bottom, right)
+
+   Create a UIEdgeInsets.
+
+   :param top: top value of the UIEdgeInsets
+   :type top: number
+   :param left: left value of the UIEdgeInsets
+   :type left: number
+   :param bottom: bottom value of the UIEdgeInsets
+   :type bottom: number
+   :param right: right value of the UIEdgeInsets
+   :type right: number
+   :return: The UIEdgeInsets struct.
+   :rtype: table$private.insets
+
+.. lua:class:: private.insets
+
+   .. visibility:: private
+
+   .. lua:attribute:: top: number
+   .. lua:attribute:: left: number
+   .. lua:attribute:: bottom: number
+   .. lua:attribute:: right: number
+```
+
+The `luadoc` builder emits the return metadata as `type:
+"objc.private.insets"` and `displayType: "table"`. Codea uses `type` for
+autocomplete and type lookup, and `displayType` for Reference display. The
+private class is authored explicitly so function arguments and returned table
+fields can differ.
+
+### Constructors
+
+Document constructors as a `lua:staticmethod` nested inside the class, using the
+same callable name as the class. The `luadoc` builder treats same-name nested
+staticmethods as constructors and emits `kind: "constructor"` in JSON, so Codea
+can show constructor rows and infer constructor return types without implying a
+`Type.Type()` API.
+
+```rst
+.. lua:class:: mesh
+
+   .. lua:staticmethod:: mesh([submeshCount])
+
+      Create an empty mesh.
+```
+
+For module-scoped and dotted classes, keep the constructor signature aligned
+with the public call:
+
+```rst
+.. lua:module:: physics2d
+
+.. lua:class:: world
+
+   .. lua:staticmethod:: world()
+```
+
+```rst
+.. lua:class:: gesture.tap
+
+   .. lua:staticmethod:: gesture.tap(callback)
+```
+
+Rules:
+
+- Use same-name nested staticmethods only for constructors.
+- Do not document a true static method with the same name as its type.
+- Repeat the same constructor staticmethod with different signatures to document
+  overloads.
+- Continue using ordinary `lua:staticmethod` entries for real static factories,
+  such as `mesh.sphere`, `image.cube`, and `shader.compute`.
+
+### Symbol Annotations
+
+Use `.. symbol::` for syntax-highlighting classifications. Symbol annotations
+are inherited by descendant API entries until a more-specific `.. symbol::`
+replaces them.
+
+Supported symbol types:
+
+- `api-call`: Codea API call highlighting. This is the default for docs-derived
+  functions when no symbol metadata is present.
+- `lua-api`: Lua standard library highlighting.
+- `const`: Constant highlighting. This maps to Codea's existing constant symbol
+  type.
+
+Examples:
+
+```rst
+.. symbol:: lua-api
+
+.. lua:function:: print(...)
+
+.. lua:attribute:: pi: const
+
+   .. symbol:: lua-api const
+```
+
+```rst
+.. lua:attribute:: STANDARD: const
+
+   .. symbol:: const
+      :group: viewer-mode
+```
+
+The optional `:group:` value is emitted as `symbol.group`. Codea can use this to
+identify replaceable symbol sets, such as viewer modes, text alignment values,
+bit masks, or other related constants.
+
+Use symbol annotations for semantic coloring and symbol-map behavior. Do not use
+them for popover/editor UI features.
+
+### Editor Annotations
+
+Use `.. editor::` for editor affordances only. These roles are emitted as editor
+metadata and mapped by Codea to existing `LuaSymbolType` affordance flags.
+
+Supported roles include:
+
+- `color`: color picker affordance
+- `sprite`: sprite/image asset affordance
+- `text`: text/font-related affordance
+- `import`: asset import affordance, for APIs such as `require`
+- `sound`: sound asset affordance
+- `music`: music asset affordance
+- `font`: font picker affordance
+- `shader`: shader affordance
+- `model`: model asset affordance
+
+Example:
+
+```rst
+.. lua:function:: fill(<color>)
+
+   Sets the fill color.
+
+   .. editor:: color
+```
+
+This lets Codea derive `style.fill` as both an API call and a color API call, so
+the editor can apply the correct highlighting and show the color interaction.
+
+Keep editor roles separate from symbol classifications:
+
+- Use `.. symbol:: lua-api` for Lua API coloring.
+- Use `.. symbol:: const` for constant coloring.
+- Use `.. editor:: color`, `sprite`, `import`, etc. only when tapping or editing
+  the symbol should expose a special editor interaction.
+
 ## Scripts
 
 ### `scripts/check_helptexts.py`

docs/source/api/graphics.rst

@@ -6,11 +6,31 @@ graphics commands
 Background
 ##########
 
-.. lua:function:: background(<color>)
+.. lua:function:: background(red, green, blue, alpha)
 
    Clears the current context with solid color, can also be used to set image backgrounds when combined with :lua:func:`context.push`
 
-   .. helptext:: set the background color, image or shader
+   :param red: The red component of the color (0-255)
+   :type red: number
+   :param green: The green component of the color (0-255)
+   :type green: number
+   :param blue: The blue component of the color (0-255)
+   :type blue: number
+   :param alpha: The alpha component of the color (0-255)
+   :type alpha: number
+
+   .. helptext:: set the background color
+   .. editor:: color
+
+.. lua:function:: background(color)
+
+   Clears the current context with solid color, can also be used to set image backgrounds when combined with :lua:func:`context.push`
+
+   :param color: The color to set the background to
+   :type color: color
+
+   .. helptext:: set the background color
+   .. editor:: color      
 
 .. lua:function:: background(cubeImage, [mipLevel = 0])
 
@@ -19,12 +39,17 @@ Background
    .. helptext:: clear the background with a cube image
 
    :param cubeImage: The image to clear the background with
+   :type cubeImage: image
    :param mipLevel: The mip level of the image to use, useful for displaying pre-blurred image mips, such as those calculated using :lua:meth:`image.generateIrradiance`
+   :type mipLevel: number
 
 .. lua:function:: background(shader)
 
    Clears the current background using a custom shader
 
+   :param shader: The shader to use when clearing the background, should be a shader that is compatible with sprite rendering (i.e. uses the same vertex attributes)
+   :type shader: shader
+
    .. helptext:: clear the background with a shader
 
    .. collapse:: Example
@@ -41,6 +66,15 @@ A set of graphics functions which are so commonly used they are in the global na
 
    Draws 2D line from the start point (x1, y1) to the end point (x2, y2) based on the current style:
 
+   :param x1: the x coordinate of the start point
+   :type x1: number
+   :param y1: the y coordinate of the start point
+   :type y1: number
+   :param x2: the x coordinate of the end point
+   :type x2: number
+   :param y2: the y coordinate of the end point
+   :type y2: number
+
    - *Color* with :lua:func:`style.stroke`
    - *Width* with :lua:func:`style.strokeWidth`
    - *End Caps* with :lua:func:`style.lineCapMode`
@@ -111,11 +145,17 @@ A set of graphics functions which are so commonly used they are in the global na
    Draws a 2D arc with a given origin, radius and start, end angles + direction
 
    :param x: x coordinate of the arc origin
+   :type x: number
    :param y: y coordinate of the arc origin
+   :type y: number
    :param radius: the radius arc
+   :type radius: number
    :param startAngle: the start angle of the arc (in degrees)
+   :type startAngle: number
    :param endAngle: the end angle of the arc (in degrees)
+   :type endAngle: number
    :param dir: the direction of the arc, 1 or clockwise, -1 for anti-clockwise
+   :type dir: integer
 
    .. helptext:: draw a 2D arc
 
@@ -126,16 +166,51 @@ A set of graphics functions which are so commonly used they are in the global na
 
    .. helptext:: draw a circle or oval
 
-.. lua:function:: rect(x, y, w, h)
-                  rect(x, y, w, h, r)
-                  rect(x, y, w, h, r1, r2, r3, r4)
+.. lua:function:: rect(x, y, w, h, [radius = 0])
 
    Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on :lua:func:`style.shapeMode`
 
-   Additional arguments allow for rounded corners (either all one radius or four separate radii)
+   Optional parameter ``radius`` specified the corner radius
+
+   :param x: the x coordinate of the rectangle
+   :type x: number
+   :param y: the y coordinate of the rectangle
+   :type y: number
+   :param w: the width of the rectangle
+   :type w: number
+   :param h: the height of the rectangle
+   :type h: number
+   :param radius: the radius of the rounded corners
+   :type radius: number
 
    .. helptext:: draw a rectangle
 
+.. lua:function:: rect(x, y, w, h, r1, r2, r3, r4)
+
+   Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on :lua:func:`style.shapeMode`
+
+   The corner radius of each corner can be set independently using the additional parameters r1, r2, r3 and r4
+
+   :param x: the x coordinate of the rectangle
+   :type x: number
+   :param y: the y coordinate of the rectangle
+   :type y: number
+   :param w: the width of the rectangle
+   :type w: number
+   :param h: the height of the rectangle
+   :type h: number
+   :param r1: the radius of the top-left corner
+   :type r1: number
+   :param r2: the radius of the top-right corner
+   :type r2: number
+   :param r3: the radius of the bottom-right corner
+   :type r3: number
+   :param r4: the radius of the bottom-left corner
+   :type r4: number
+
+   .. helptext:: draw a rectangle with rounded corners      
+
+
 Sprites
 #######
 
@@ -146,11 +221,13 @@ Sprites
    Draws a sprite using an asset - :lua:class:`image`, :lua:class:`asset.key` or :lua:class:`sprite.slice`
 
    .. helptext:: draw a sprite or image
+   .. editor:: sprite
 
 
 .. lua:function:: sprite(shader, x, y, w, h)
 
    .. helptext:: draw using a shader
+   .. editor:: shader
 
 
 Text
@@ -161,6 +238,7 @@ Text
    Draws one or more lines of text based on the current style. Use the optional width and height parameters to draw a fixed size text box with line wrapping enabled
 
    .. helptext:: draw text at a location
+   .. editor:: text
 
    - *Text Color* with :lua:func:`style.fill`
    - *Text Outline* with :lua:func:`style.stroke`