twix/raylib
1
0
Fork 0
mirror of https://github.com/raysan5/raylib.git synced 2025-12-25 10:22:33 -05:00
Code Issues Packages Projects Releases Wiki Activity

Updated raylib syntax analysis (markdown)

Ray
2021-06-01 19:46:42 +02:00
parent bf2c74051b
commit f215c00f1e
1 changed files with 86 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
raylib-syntax-analysis.md

@ -1,14 +1,14 @@
raylib is a simple and easy-to-use library to enjoy videogames programing... but, **what makes the library simple and easy-to-use?** Considering that for many users the first contact with the library is its API, here it is a small analysis of the API from a **syntactic point of view**. How are the functions structured? Which words are used? How many parameters are exposed? How intuitive is it to understand or even guess every function/structure/enum when required?
raylib is a simple and easy-to-use library to enjoy videogames programing... but, **what makes the library simple and easy-to-use?** For many users the first approach to the library is through its API, so, here it is a small analysis of the API from a **syntactic point of view**.
Syntax is the set of rules, principles, and processes that govern the structure of sentences in a given language, usually including word order.
How are the functions structured? Which words are used? How many parameters are exposed? How intuitive is it to understand or even guess every function/structure/enum when required? Syntax is the set of rules, principles, and processes that govern the structure of sentences in a given language, including word order.
To do this analysis a [`raylib.h` parser](https://github.com/raysan5/raylib/tree/master/parser) has been created. That parser dissects API into small pieces; in the future it can also be useful for automatic docs and binding generation!
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 values for a specific type of data
- **Functions**: Instructions called by the users to make things happen
- **Structures (`struct`)**: Data types to organize information packages
- **Enumerators (`enum`)**: Sequence of values for a specific type of data
## Functions
@ -23,9 +23,9 @@ More specifically, every syntactic element implies:
<Action><Object><Attribute/State>(); // Do an Action over some Object Attribute/State
```
Following this rule make the API comprehensive, intuitive, easy-to-remember and easy-to-use.
**Following this rule make the API comprehensive, intuitive, easy-to-remember and easy-to-use.**
Checking the available functions with more detail, they can be divided into 3 groups:
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
@ -33,7 +33,7 @@ Checking the available functions with more detail, they can be divided into 3 gr
### 1. Functions following a common pattern
Most of the functions of the library go into this first group **(~360)**, there are some common `<Action>` that prepend the name of most of the functions:
Most of the functions of the library go into this first group **(359 funtions)**, there are some common `<Action>` that prepend the name of most of the functions:
pattern | function format | API count | examples
:--: | :----- | :---: | :----------
@ -55,7 +55,7 @@ pattern | function format | API count | examples
### 2. Functions operating over specific type of data
Those functions 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:
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:
pattern | function format | API count | examples
:--: | :----- | :---: | :----------
@ -99,7 +99,7 @@ DecompressData();
OpenURL();
// textures.c
Fade(); // Left for backward compatibility, use ColorAlpha() instead
Fade(); // Superseded by ColorAlpha()
// text.c
MeasureText();
@ -128,13 +128,77 @@ ResumeAudioStream();
### Functions naming
Most functions in raylib use a maximum of 4 words
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:
count| function | words | comments
:--: | :----- | :---: | :----------
001 | GetWindowScaleDPI() | 4 | _Acronym used_
002 | GetWorldToScreenEx() | 5 |
003 | GetWorldToScreen2D() | 5 |
004 | GetScreenToWorld2D() | 5 |
005 | SetTargetFPS() | 5 | _Acronym used_
006 | SetLoadFileDataCallback() | 5 | _Callback function_
007 | SetSaveFileDataCallback() | 5 | _Callback function_
008 | SetLoadFileTextCallback() | 5 | _Callback function_
009 | SetSaveFileTextCallback() | 5 | _Callback function_
010 | GetFileNameWithoutExt() | 5 |
011 | SetCameraSmoothZoomControl() | 5 | TODO: Review!!!
012 | ImageToPOT() | 3 | _Acronym used_
013 | ImageRotateCCW() | 3 | _Acronym used_
014 | ColorToHSV() | 3 | _Acronym used_
015 | ColorFromHSV() | 3 | _Acronym used_
016 | LoadMusicStreamFromMemory() | 5 | _*FromMemory() set of functions_
017 | SetAudioStreamBufferSizeDefault() | **6** | **TODO: Review!!!**
### 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**:
count| function | param count | comments
:--: | :----- | :--: | :----------
001 | SetCameraMoveControls() | 6 |
002 | DrawCircleSector() | 6 |
003 | DrawCircleSectorLines() | 6 |
004 | DrawRing() | 7 | _WARNING: >6 parameters_
005 | DrawRingLines() | 7 | _WARNING: >6 parameters_
006 | DrawRectangleGradientV() | 6 |
007 | DrawRectangleGradientH() | 6 |
008 | DrawPolyLinesEx() | 6 |
009 | GenImageChecked() | 6 |
010 | ImageResizeCanvas() | 6 |
011 | ImageDrawLine() | 6 |
012 | ImageDrawRectangle() | 6 |
013 | ImageDrawText() | 6 |
014 | ImageDrawTextEx() | 7 | _WARNING: >6 parameters_
015 | DrawTextureTiled() | 7 | _WARNING: >6 parameters_
016 | DrawTexturePro() | 6 |
017 | DrawTextureNPatch() | 6 |
018 | DrawTexturePoly() | 6 |
019 | LoadFontFromMemory() | 6 |
020 | LoadFontData() | 6 |
021 | GenImageFontAtlas() | 6 |
022 | DrawTextEx() | 6 |
023 | DrawTextRec() | 7 | _WARNING: >6 parameters_
024 | DrawTextRecEx() | **11** | **TODO: Review!!!**
025 | DrawCubeTexture() | 6 |
026 | DrawCylinder() | 6 |
027 | DrawCylinderWires() | 6 |
028 | DrawModelEx() | 6 |
029 | DrawModelWiresEx() | 6 |
030 | DrawBillboardRec() | 6 |
031 | DrawBillboardPro() | 8 | _WARNING: >6 parameters_
Note that **only 7 function out of 470** require more than 6 parameters. This is what makes raylib so special.
## 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.
num | struct name | fields count | comments
raylib tries to provide generic data types for most common use scenarios, only some of those structs are required for specific examples: `NPatchInfo`, `VrDeviceInfo`, `VrStereoConfig`.
About the fields contained in every struct, it was tried to just include the minimum required but when moving into 3d `Mesh` and `Model`, the amount of required data grows fast. For a more detailed analysis on data structures (not purely syntactic), check Wiki entry: [raylib data structures](https://github.com/raysan5/raylib/wiki/raylib-data-structures).
count | struct name | fields count | comments
:--:| :---------: | :-------: | :--------
01 | Vector2 | 2 |
02 | Vector3 | 3 |
@ -170,7 +234,11 @@ num | struct name | fields count | comments
## Enumerations
num | enum name | values count | comments
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).
Personally, I tried to avoid enum values requirement as much as possible within the library, actually, **only 35 function in raylib could require using some enum value on some of its input parameters**.
count | enum name | values count | comments
:--:| :---------: | :-------: | :--------
01 | ConfigFlags | 14 |
02 | TraceLogLevel | 8 | _3 words name_
@ -191,4 +259,8 @@ num | enum name | values count | comments
17 | Gestures | 11 |
18 | CameraMode | 5 |
19 | CameraProjection | 2 |
20 | NPatchLayout | 3 | _3 words name_
20 | NPatchLayout | 3 | _3 words name_
## Conclusion
One of the goals of raylib is being simple and easy-to-use and many hours have been put into the API design; thinking about the best name for every function, the minimum number of parameters required, the name of each parameter, the data types required... This syntax analysis is a good way to see what worked for this library and how it can be improved.