[Documentation] Summary & Readability improvement (#125)

README.md

@@ -151,6 +151,62 @@ In summary, the general order of steps is:
 
 For help starting out or to discuss clay, considering joining [the discord server.](https://discord.gg/b4FTWkxdvT)
 
+## Summary
+
+- [High Level Documentation](#high-level-documentation)
+  - [Building UI Hierarchies](#building-ui-hierarchies)
+  - [Configuring Layout and Styling UI Elements](#configuring-layout-and-styling-ui-elements)
+  - [Element IDs](#element-ids)
+  - [Mouse, Touch and Pointer Interactions](#mouse-touch-and-pointer-interactions)
+  - [Scrolling Elements](#scrolling-elements)
+  - [Floating Elements](#floating-elements-absolute-positioning)
+  - [Custom Elements](#laying-out-your-own-custom-elements)
+  - [Retained Mode Rendering](#retained-mode-rendering)
+  - [Visibility Culling](#visibility-culling)
+  - [Preprocessor Directives](#preprocessor-directives)
+  - [Bindings](#bindings-for-non-c)
+  - [Debug Tools](#debug-tools)
+- [API](#api)
+  - [Naming Conventions](#naming-conventions)
+  - [Public Functions](#public-functions)
+    - [Lifecycle](#lifecycle-for-public-functions)
+    - [Clay_MinMemorySize](#clay_minmemorysize)
+    - [Clay_CreateArenaWithCapacityAndMemory](#clay_createarenawithcapacityandmemory)
+    - [Clay_SetMeasureTextFunction](#clay_setmeasuretextfunction)
+    - [Clay_SetMaxElementCount](clay_setmaxelementcount)
+    - [Clay_SetMaxMeasureTextCacheWordCount](#clay_setmaxmeasuretextcachewordcount)
+    - [Clay_Initialize](#clay_initialize)
+    - [Clay_SetLayoutDimensions](#clay_setlayoutdimensions)
+    - [Clay_SetPointerState](#clay_setpointerstate)
+    - [Clay_UpdateScrollContainers](#clay_updatescrollcontainers)
+    - [Clay_BeginLayout](#clay_beginlayout)
+    - [Clay_EndLayout](#clay_endlayout)
+    - [Clay_Hovered](#clay_hovered)
+    - [Clay_OnHover](#clay_onhover)
+    - [Clay_PointerOver](#clay_pointerover)
+    - [Clay_GetScrollContainerData](#clay_getscrollcontainerdata)
+    - [Clay_GetElementId](#clay_getelementid)
+  - [Element Macros](#element-macros)
+    - [CLAY](#clay-1)
+    - [CLAY_ID](#clay_id)
+    - [CLAY_IDI](#clay_idi)
+    - [CLAY_LAYOUT](#clay_layout)
+    - [CLAY_RECTANGLE](#clay_rectangle)
+    - [CLAY_TEXT](#clay_text)
+    - [CLAY_IMAGE](#clay_image)
+    - [CLAY_SCROLL](#clay_scroll)
+    - [CLAY_BORDER](#clay_border)
+    - [CLAY_FLOATING](#clay_floating)
+    - [CLAY_CUSTOM_ELEMENT](#clay_custom_element)
+  - [Data Structures & Defs](data-structures--definitions)
+    - [Clay_String](#clay_string)
+    - [Clay_ElementId](#clay_elementid)
+    - [Clay_RenderCommandArray](#clay_rendercommandarray)
+    - [Clay_RenderCommand](#clay_rendercommand)
+    - [Clay_ScrollContainerData](#clay_scrollcontainerdata)
+    - [Clay_ErrorHandler](#clay_errorhandler)
+    - [Clay_ErrorData](#clay_errordata)
+
 ## High Level Documentation
 
 ### Building UI Hierarchies
@@ -490,18 +546,24 @@ render(renderCommands2);
 **Each Frame**
 `Clay_SetLayoutDimensions` -> `Clay_SetPointerState` -> `Clay_UpdateScrollContainers` -> `Clay_BeginLayout` -> `CLAY() etc...` -> `Clay_EndLayout`
 
+---
+
 ### Clay_MinMemorySize
 
 `uint32_t Clay_MinMemorySize()`
 
 Returns the minimum amount of memory **in bytes** that clay needs to accomodate the current [CLAY_MAX_ELEMENT_COUNT](#preprocessor-directives).
 
+---
+
 ### Clay_CreateArenaWithCapacityAndMemory
 
 `Clay_Arena Clay_CreateArenaWithCapacityAndMemory(uint32_t capacity, void *offset)`
 
 Creates a `Clay_Arena` struct with the given capacity and base memory pointer, which can be passed to [Clay_Initialize](#clay_initialize).
 
+---
+
 ### Clay_SetMeasureTextFunction
 
 `void Clay_SetMeasureTextFunction(Clay_Dimensions (*measureTextFunction)(Clay_String *text, Clay_TextElementConfig *config))`
@@ -512,6 +574,8 @@ Takes a pointer to a function that can be used to measure the `width, height` di
 
 **Note 2: It is essential that this function is as fast as possible.** For text heavy use-cases this function is called many times, and despite the fact that clay caches text measurements internally, it can easily become the dominant overall layout cost if the provided function is slow. **This is on the hot path!**
 
+---
+
 ### Clay_SetMaxElementCount
 
 `void Clay_SetMaxElementCount(uint32_t maxElementCount)`
@@ -520,6 +584,8 @@ Sets the internal maximum element count that will be used in subsequent [Clay_In
 
 **Note: You will need to reinitialize clay, after calling [Clay_MinMemorySize()](#clay_minmemorysize) to calculate updated memory requirements.**
 
+---
+
 ### Clay_SetMaxMeasureTextCacheWordCount
 
 `void Clay_SetMaxMeasureTextCacheWordCount(uint32_t maxMeasureTextCacheWordCount)`
@@ -528,6 +594,8 @@ Sets the internal text measurement cache size that will be used in subsequent [C
 
 **Note: You will need to reinitialize clay, after calling [Clay_MinMemorySize()](#clay_minmemorysize) to calculate updated memory requirements.**
 
+---
+
 ### Clay_Initialize
 
 `Clay_Context* Clay_Initialize(Clay_Arena arena, Clay_Dimensions layoutDimensions, Clay_ErrorHandler errorHandler)`
@@ -548,18 +616,24 @@ Sets the context that subsequent clay commands will operate on. You can get this
 
 Returns the context that clay commands are currently operating on, or null if no context has been set. See [Running more than one Clay instance](#running-more-than-one-clay-instance).
 
+---
+
 ### Clay_SetLayoutDimensions
 
 `void Clay_SetLayoutDimensions(Clay_Dimensions dimensions)`
 
 Sets the internal layout dimensions. Cheap enough to be called every frame with your screen dimensions to automatically respond to window resizing, etc.
 
+---
+
 ### Clay_SetPointerState
 
 `void Clay_SetPointerState(Clay_Vector2 position, bool isPointerDown)`
 
 Sets the internal pointer position and state (i.e. current mouse / touch position) and recalculates overlap info, which is used for mouseover / click calculation (via [Clay_PointerOver](#clay_pointerover) and updating scroll containers with [Clay_UpdateScrollContainers](#clay_updatescrollcontainers). **isPointerDown should represent the current state this frame, e.g. it should be `true` for the entire duration the left mouse button is held down.** Clay has internal handling for detecting click / touch start & end.
 
+---
+
 ### Clay_UpdateScrollContainers
 
 `void Clay_UpdateScrollContainers(bool enableDragScrolling, Clay_Vector2 scrollDelta, float deltaTime)`
@@ -570,24 +644,32 @@ Touch / drag scrolling only occurs if the `enableDragScrolling` parameter is `tr
 
 `deltaTime` is the time **in seconds** since the last frame (e.g. 0.016 is **16 milliseconds**), and is used to normalize & smooth scrolling across different refresh rates.
 
+---
+
 ### Clay_BeginLayout
 
 `void Clay_BeginLayout()`
 
 Prepares clay to calculate a new layout. Called each frame / layout **before** any of the [Element Macros](#element-macros).
 
+---
+
 ### Clay_EndLayout
 
 `Clay_RenderCommandArray Clay_EndLayout()`
 
 Ends declaration of element macros and calculates the results of the current layout. Renders a [Clay_RenderCommandArray](#clay_rendercommandarray) containing the results of the layout calculation.
 
+---
+
 ### Clay_Hovered
 
 `bool Clay_Hovered()`
 
 Called **during** layout declaration, and returns `true` if the pointer position previously set with `Clay_SetPointerState` is inside the bounding box of the currently open element. Note: this is based on the element's position from the **last** frame.
 
+---
+
 ### Clay_OnHover
 
 `void Clay_OnHover(void (*onHoverFunction)(Clay_ElementId elementId, Clay_PointerData pointerData, intptr_t userData), intptr_t userData)`
@@ -612,6 +694,8 @@ CLAY(CLAY_LAYOUT({ .padding = { 8, 8 }}), Clay_OnHover(HandleButtonInteraction,
 }
 ```
 
+---
+
 ### Clay_PointerOver
 
 `bool Clay_PointerOver(Clay_ElementId id)`
@@ -624,6 +708,8 @@ Returns `true` if the pointer position previously set with `Clay_SetPointerState
 
 Returns [Clay_ScrollContainerData](#clay_scrollcontainerdata) for the scroll container matching the provided ID. This function allows imperative manipulation of scroll position, allowing you to build things such as scroll bars, buttons that "jump" to somewhere in a scroll container, etc.
 
+---
+
 ### Clay_GetElementId
 
 `Clay_ElementId Clay_GetElementId(Clay_String idString)`
@@ -665,6 +751,8 @@ CLAY(CLAY_ID("Outer"), CLAY_LAYOUT({ .padding = {16, 16} })) {
 }
 ```
 
+---
+
 ### CLAY_ID
 
 **Usage**
@@ -699,12 +787,16 @@ if (buttonIsHovered && leftMouseButtonPressed) {
 }
 ```
 
+---
+
 ### CLAY_IDI()
 
 `Clay_ElementId CLAY_IDI(char *label, int index)`
 
 An offset version of [CLAY_ID](#clay_id). Generates a [Clay_ElementId](#clay_elementid) string id from the provided `char *label`, combined with the `int index`. Used for generating ids for sequential elements (such as in a `for` loop) without having to construct dynamic strings at runtime.
 
+---
+
 ### CLAY_LAYOUT
 
 **Usage**
@@ -816,6 +908,8 @@ CLAY(CLAY_ID("Button"), CLAY_LAYOUT({ .layoutDirection = CLAY_TOP_TO_BOTTOM, .si
 }
 ``` 
 
+---
+
 ### CLAY_RECTANGLE
 **Usage**
 
@@ -897,6 +991,8 @@ CLAY(
 }
 ```
 
+---
+
 ### CLAY_TEXT
 **Usage**
 
@@ -1018,6 +1114,8 @@ Element is subject to [culling](#visibility-culling). Otherwise, multiple `Clay_
 
 `Clay_RenderCommand.textContent` will be populated with a `Clay_String` _slice_ of the original string passed in (i.e. wrapping doesn't reallocate, it just returns a `Clay_String` pointing to the start of the new line with a `length`)
 
+---
+
 ### CLAY_IMAGE
 **Usage**
 
@@ -1115,6 +1213,8 @@ Image *imageToRender = renderCommand->elementConfig.imageElementConfig->imageDat
 
 Element is subject to [culling](#visibility-culling). Otherwise, a single `Clay_RenderCommand`s with `commandType = CLAY_RENDER_COMMAND_TYPE_IMAGE` will be created. The user will need to access `renderCommand->elementConfig.imageElementConfig->imageData` to retrieve image data referenced during layout creation. It's also up to the user to decide how / if they wish to blend `rectangleElementConfig->color` with the image.
 
+---
+
 ### CLAY_SCROLL
 **Usage**
 
@@ -1174,6 +1274,8 @@ CLAY(CLAY_SCROLL(.vertical = true)) {
 }
 ```
 
+---
+
 ### CLAY_BORDER
 **Usage**
 
@@ -1291,6 +1393,8 @@ CLAY(
 Element is subject to [culling](#visibility-culling). Otherwise, a single `Clay_RenderCommand` with `commandType = CLAY_RENDER_COMMAND_TYPE_BORDER` representing the container will be created.
 Rendering of borders and rounded corners is left up to the user. See the provided [Raylib Renderer](https://github.com/nicbarker/clay/tree/main/renderers/raylib) for examples of how to draw borders using line and curve primitives.
 
+---
+
 ### CLAY_FLOATING
 **Usage**
 
@@ -1502,6 +1606,8 @@ When using `.parentId`, the floating container can be declared anywhere after `B
 
 `CLAY_FLOATING` elements will not generate any render commands.
 
+---
+
 ### CLAY_CUSTOM_ELEMENT
 **Usage**
 
@@ -1628,6 +1734,8 @@ The number of characters in the string, _not including an optional null terminat
 
 A pointer to the contents of the string. This data is not guaranteed to be null terminated, so if you are passing it to code that expects standard null terminated C strings, you will need to copy the data and append a null terminator.
 
+---
+
 ### Clay_ElementId
 
 ```C
@@ -1665,6 +1773,7 @@ If this id was generated using [CLAY_IDI](#clay_idi), `.baseId` is the hash of t
 
 Stores the original string that was passed in when [CLAY_ID](#clay_id) or [CLAY_IDI](#clay_idi) were called.
 
+---
 
 ### Clay_RenderCommandArray
 
@@ -1698,6 +1807,8 @@ Represents the total number of `Clay_RenderCommand` elements stored consecutivel
 
 An array of [Clay_RenderCommand](#clay_rendercommand)s representing the calculated layout. If there was at least one render command, this array will contain elements from `.internalArray[0]` to `.internalArray[.length - 1]`.
 
+---
+
 ### Clay_RenderCommand
 
 ```C
@@ -1764,6 +1875,8 @@ Only used if `.commandType == CLAY_RENDER_COMMAND_TYPE_TEXT`. A `Clay_String` co
 
 The id that was originally used with the element macro that created this render command. See [CLAY_ID](#clay_id) for details.
 
+---
+
 ### Clay_ScrollContainerData
 
 ```C
@@ -1813,6 +1926,8 @@ Dimensions representing the inner width and height of the content _inside_ the s
 
 The [Clay_ScrollElementConfig](#clay_scroll) for the matching scroll container element.
 
+---
+
 ### Clay_PointerData
 
 ```C