Created raylib syntax analysis (markdown)

4 年前 · bf2c74051b
--- a/raylib-syntax-analysis.md
+++ b/raylib-syntax-analysis.md
@ -0,0 +1,194 @@
 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?

 Syntax is the set of rules, principles, and processes that govern the structure of sentences in a given language, usually 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

 Latest raylib version in the moment of this writing (3.8-dev) exposes a total of **470 functions**, a relatively small API for a gamedev library.

 All raylib functions _try_ to follow this syntactic structure:
 ```
    <Verb><Subject><Complement>();
 ```
 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.

 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. 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:

 pattern | function format | API count | examples
 :--: | :----- | :---: | :----------
 01 | void Init*()                   | 3   | InitWindow(), InitAudioDevice(), InitAudioStream()
 02 | void Close*()                  | 3   | CloseWindow(), CloseAudioDevice(), CloseAudioStream()
 03 | void Begin*()                  | 8   | BeginDrawing(), BeginBlendMode()
 04 | void End*()                    | 8   | EndDrawing(), EndBlendMode()
 05 | TYPE Get*()                    | **79**  | GetKeyPressed(), GetMouseX(), GetRayCollision*()
 06 | void Set*()                    | **46**  | SetWindowTitle(), SetTargetFPS(), SetMouseScale()
 07 | bool Is*()                     | **33**  | IsKeyPressed(), IsGamepadAvailable(), IsSoundPlaying()
 08 | TYPE Gen<TYPE>*()              | 20  | GenImage*(), GenMesh*()
 09 | TYPE Load<TYPE>*()             | **33**  | LoadImage*(), LoadTexture*(), LoadSound*()
 10 | void Unload<TYPE>*(<TYPE>)     | 21  | UnloadImage(), UnloadTexture(), UnloadSound()
 11 | void Update<TYPE>*(<TYPE>, *)  | 8   | UpdateTexture(), UpdateCamera()
 12 | bool Save*()                   | 3   | SaveFileData(), SaveFileText(), SaveStorageValue()
 13 | bool Export*()                 | 5   | ExportImage(), ExportImageAsCode(), ExportMesh(), ExportWave(), ExportWaveAsCode()
 14 | void Draw*()                   | **79**  | DrawRectangle(), DrawTexture*(), DrawModel*()
 15 | bool CheckCollision*()         | 10  | CheckCollisionRecs(), CheckCollisionCircles(), CheckCollisionBoxSphere()

 ### 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: 

 pattern | function format | API count | examples
 :--: | :----- | :---: | :----------
 01 | TYPE Color*()        | 7    | ColorAlpha(), ColorFromHSV(), ColorToHSV()
 02 | Image/void Image*()  | **40**   | ImageFormat(), ImageCrop(), ImageResize(), ImageFlipVertical()
 03 | TYPE Text*()         | **16**   | TextFormat(), TextReplace(), TextSplit(), TextToLower()
 04 | Mesh*()              | 2    | MeshTangents(), MeshBinormals()
 05 | Wave/void Wave*()    | 3    | WaveFormat(), WaveCopy(), WaveCrop()

 _NOTE: Maybe some of them are renamed in the future for consistency._

 ### 3. Functions with unique pattern

 Remaining functions **(43 in total)** follow a unique pattern, still, **most of them** follow the standard syntax pattern of `<Verb><Subject><Complement>`.

 ```c
 // core.c
 WindowShouldClose();   // Not following pattern
 ClearWindowState();
 ToggleFullscreen();
 MaximizeWindow();
 MinimizeWindow();
 RestoreWindow();
 ShowCursor();
 HideCursor();
 EnableCursor();
 DisableCursor();
 ClearBackground();
 TakeScreenshot();
 TraceLog();            // Not following pattern
 MemAlloc();            // Data-type pattern?
 MemRealloc();          // Data-type pattern?
 MemFree();             // Data-type pattern?
 FileExists();          // Not following pattern -> IsFileAvailable()?
 DirectoryExists();     // Not following pattern -> IsDirectoryAvailable()?
 ClearDirectoryFiles();
 ChangeDirectory();
 ClearDroppedFiles();
 CompressData();
 DecompressData();
 OpenURL();

 // textures.c
 Fade();                // Left for backward compatibility, use ColorAlpha() instead

 // text.c
 MeasureText();
 MeasureTextEx();
 CodepointToUtf8();     // Not following pattern -> EncodeCodepointAsUtf8()?

 // models.c
 UploadMesh();

 // raudio.c
 PlaySound();
 StopSound();
 PauseSound();
 ResumeSound();
 PlaySoundMulti();
 StopSoundMulti();
 PlayMusicStream();
 StopMusicStream();
 PauseMusicStream();
 ResumeMusicStream();
 PlayAudioStream();
 StopAudioStream();
 PauseAudioStream();
 ResumeAudioStream();
 ```

 ### Functions naming

 Most functions in raylib use a maximum of 4 words

 ## 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
 :--:| :---------: | :-------: | :--------
 01  |  Vector2       |   2   |  
 02  |  Vector3       |   3   |  
 03  |  Vector4       |   4   |  
 04  |  Matrix        |   4   |  
 05  |  Color         |   4   |  
 06  |  Rectangle     |   4   |  
 07  |  Image         |   5   |  
 08  |  Texture       |   5   |  
 09  |  RenderTexture |   3   |  _2 words name_
 10  |  NPatchInfo    |   6   |  _2 words name_
 11  |  CharInfo      |   5   |  
 12  |  Font          |   6   |  
 13  |  Camera3D      |   5   |  
 14  |  Camera2D      |   4   |  
 15  |  Mesh          |  **15**  |  
 16  |  Shader        |   2   |  
 17  |  MaterialMap   |   3   |  _2 words name_
 18  |  Material      |   3   |  
 19  |  Transform     |   3   |  
 20  |  BoneInfo      |   2   |  
 21  |  Model         |  **9**   |  
 22  |  ModelAnimation|   4   |  _2 words name_
 23  |  Ray           |   2   |  
 24  |  RayCollision  |   4   |  _2 words name_
 25  |  BoundingBox   |   2   |  _2 words name_
 26  |  Wave          |   5   |  
 27  |  AudioStream   |   4   |  _2 words name_
 28  |  Sound         |   2   |  
 29  |  Music         |   5   |  
 30  |  VrDeviceInfo   |  **10**  |  _3 words name_
 31  |  VrStereoConfig |  **8**   |  _3 words name_

 ## Enumerations

 num  | enum name | values count | comments
 :--:| :---------: | :-------: | :--------
 01 |  ConfigFlags           | 14   |        
 02 |  TraceLogLevel         | 8    | _3 words name_
 03 |  KeyboardKey           | **110**  | 
 04 |  MouseButton           | 8    | 
 05 |  MouseCursor           | 11   | 
 06 |  GamepadButton         | **18**   | 
 07 |  GamepadAxis           | 6    | 
 08 |  MaterialMapIndex      | 11   | _3 words name_
 09 |  ShaderLocationIndex   | **26**   | _3 words name_
 10 |  ShaderUniformDataType | 9    | **_4 words name_**
 11 |  PixelFormat           | **21**   | 
 12 |  TextureFilter         | 6    | 
 13 |  TextureWrap           | 4    | 
 14 |  CubemapLayout         | 6    | 
 15 |  FontType              | 3    | 
 16 |  BlendMode             | 6    | 
 17 |  Gestures              | 11   | 
 18 |  CameraMode            | 5    | 
 19 |  CameraProjection      | 2    | 
 20 |  NPatchLayout          | 3    | _3 words name_