Raylib: Add API Documentation via Doxygen

[RobLoach]

While the raylib cheatsheet is great to get function hints as to what functions are available and what they do, it doesn't really go into detail into how the methods work.

Adding API doc comments in the doxygen format will allow us to add a lot of detail for each method.

Example

/**
 * Initialize the window and OpenGL context.
 *
 * @param width The width of the window
 * @param height The height of the window
 * @param title The title for the window
 */
void InitWindow(int width, int height, const char *title);

It could exist in the sources itself, rather than raylib.h, just to allow the header itself to be small. Scanning the source with doxygen would generate nice API docs.

[Gamerfiend]

So, instead of the camera functions having their docs in raylib.h, they would be in camera.h?

[RobLoach]

That's a possibility. Could exist in raylib.h instead! Mostly would be great to have more API docs, anywhere really.

[Gamerfiend]

I think it would be better in raylib.h, that's where I go to look up functions and such.

[raysan5]

Personally, I don"t like Doxygen, I find it cumbersome and redundant in most cases, also it increases considerably the files size. For that reason I tried to be very clear on functions naming and parameters, trying to make them self-explanatory to reduce required documentation.

All additional information for not that clear functions could be provided through comments on examples, also more illustrative than a plain explanation...

But I'm open for some documentation not intrusive with code.

[raysan5]

No plans to add Doxygen documentation. Closing the issue for now.

[Gamerfiend]

One comment on this.. perhaps we could have a second raylib header, just be a reflection of the current one like raylib_doc.h where all documentation can be

[raysan5]

@Gamerfiend Sorry but that implies a maintenance cost that at this moment I can't assume, it can also be confusing for people checking the repo. Easier approach to documentation would be some pages (or only one page) in the Wiki of the project (anyone can edit it).