From e15001e224c89dcc2994dda9a740297d4368866f Mon Sep 17 00:00:00 2001 From: Ray Date: Fri, 3 Jun 2022 10:32:07 +0200 Subject: [PATCH] Updated raylib syntax analysis (markdown) --- raylib-syntax-analysis.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/raylib-syntax-analysis.md b/raylib-syntax-analysis.md index d33a54a..8d839aa 100644 --- a/raylib-syntax-analysis.md +++ b/raylib-syntax-analysis.md @@ -6,11 +6,11 @@ To do this analysis a [`raylib.h` parser](https://github.com/raysan5/raylib/tree The analysis is organized in 3 parts, one for each API element analyzed: - - **Functions**: Instructions called by the users to make things happen - - **Structures (`struct`)**: Data types to organize information packages - - **Enumerators (`enum`)**: Sequence of named values used for convenience + - **1. Functions**: Instructions called by the users to make things happen + - **2. Structures (`struct`)**: Data types to organize information packages + - **3. Enumerators (`enum`)**: Sequence of named values used for convenience -## Functions +## 1. Functions Latest raylib version (3.8-dev) exposes a total of **470 functions**, a relatively small API for a gamedev library. @@ -27,11 +27,14 @@ More specifically, every syntactic element implies: Checking the available **functions** with more detail, they can be divided into **3 groups**: - 1. Functions following a common pattern - 2. Functions operating over specific type of data - 3. Functions with unique pattern + - 1.1. Functions following a common pattern + - 1.2. Functions operating over specific type of data + - 1.3. Functions with unique pattern + - 1.4. Functions suffixes + - 1.5. Functions naming + - 1.6. Functions parameters -### 1. Functions following a common pattern +### 1.1. Functions following a common pattern Most of the functions of the library go into this first group **(359 functions)**, there is some common `` that prepends the name of most of the functions: @@ -53,7 +56,7 @@ pattern | function format | API count | examples 14 | `void Draw*()` | **79** | `DrawRectangle()`, `DrawTexture*()`, `DrawModel*()` 15 | `bool Check*()` | 10 | `CheckCollisionRecs()`, `CheckCollisionCircles()`, `CheckCollisionBoxSphere()` -### 2. Functions operating over specific type of data +### 1.2. Functions operating over specific type of data Those functions **(68 in total)** operate over a specific data type, so, it was decided to prepend the `DataType` to the function name, they are an exception over the main syntax rule followed by the API: @@ -66,7 +69,7 @@ pattern | function format | API count | examples _NOTE: Maybe some of them are renamed in the future for consistency._ -### 3. Functions with unique pattern +### 1.3. Functions with unique pattern Remaining functions **(43 in total)** follow a unique pattern, still, **most of them** follow the standard syntax pattern of ``. @@ -125,7 +128,7 @@ PauseAudioStream(); ResumeAudioStream(); ``` -### 4. Functions suffixes +### 1.4. Functions suffixes A part from the function prefixes that we can find in many functions names (1. common patterns), we can also find some common suffixes used by several functions: @@ -214,7 +217,7 @@ void SetLoadFileTextCallback(); void SetSaveFileTextCallback(); ``` -### 5. Functions naming +### 1.5. Functions naming Most functions in raylib use a **maximum of 4 words** on its name. I think that's a good trade-off to remember the name of the function. Still, there is a small set of functions that go beyond that limit: @@ -238,7 +241,7 @@ count| function | words | comments 016 | `LoadMusicStreamFromMemory()` | 5 | _*FromMemory() set of functions_ 017 | `SetAudioStreamBufferSizeDefault()` | **6** | **TODO: Review!!!** -### 6. Functions parameters +### 1.6. Functions parameters Most functions are limited to **5 or less input parameters**. I think 5 or less parameters is a good number to keep the function simple and rememberable, more than 5 usually requires the user to use some kind of intellisense system. **The number of parameters is a key point for raylib simplicity**, still, there are some functions requiring **6 or more parameters**: @@ -277,7 +280,7 @@ count| function | param count | comments Note that **only 6 function out of 470** require more than 6 parameters. This is what makes raylib so special. -## Structures +## 2. Structures raylib defines a total of **31 struct data types**, most of those structs use a single word to define the type and some of them use two words. @@ -319,7 +322,7 @@ count | struct name | fields count | comments 30 | `VrDeviceInfo` | **10** | _3 words name_ 31 | `VrStereoConfig` | **8** | _3 words name_ -## Enumerations +## 3. Enumerations raylib defines **20 enumerations** for convenience. Enum names and contained value names are kept simple and clear. Most of those values are only required to be used by some very specific functions, for a detailed list check Wiki entry: [raylib enumerated types](https://github.com/raysan5/raylib/wiki/raylib-enumerated-types).