diff --git a/raylib-syntax-analysis.md b/raylib-syntax-analysis.md index d82ffc2..0b583e5 100644 --- a/raylib-syntax-analysis.md +++ b/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: (); // 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 `` 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 `` 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_ \ No newline at end of file +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. \ No newline at end of file