Updated raylib syntax analysis (markdown)

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
+ - **Functions**: Instructions called by the users to make things happen
- - Structures (`struct`): Data types to organize information packages
+ - **Structures (`struct`)**: Data types to organize information packages
- - Enumerators (`enum`): Sequence of values for a specific type of data 
+ - **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.