Lack of documentation?

[leowribeiro]

Why is it that RAYLIB is so POORLY documented?
Look at SDL2, for instance, you can pick the API Reference by category and by function name.... extremely useful.
With raylib I have to keep going to the source code to see what some of the functions actually do, that's not very productive.
Sometimes I think people don't take RAYLIB seriouly because of that, look how famous SDL2 is and how many professional games have been written with it.

[raysan5]

@leowribeiro Personally, I don't think raylib is "POORLY" documented. It has a cheatsheet, a Wiki, +120 code examples and an active Discord community to learn from.

I can understand that you could not be used to that kind of learning materials and you prefer other kind of API documentation BUT current raylib materials have worked very well for many users to date.

Also note that raylib is an open source project mostly maintained by a single person, that makes maintenance very difficult and adding additional docs to maintain is not feasible BUT feel-free to add them yourself if you are ready to maintain them for the following years, that's the magic of open-source.

SDL2 is a completely different library than raylib, actually it's an amazing library, I've been teaching how to use it in University for the last 2 years. If you think it fits your educational/professional needs better than raylib I highly recommend switching to it. As you said it's probably better documented than raylib and there are many professional videogames made with it.

[orcmid]

Well, considering the response Ramon has already given, I guess the question is when you see these, have a question, and satisfy yourself, maybe there is a place to contribute to the documentation. It's all volunteers scratching an itch.

I was looking into the User options page for a game, and it specified, in key mappings, functions that go with "Button 0" and "Button 1." There are also little in-circle colored symbols, which may have been the buttons on some controller in the day, but I have no idea how those map to my Amazon Luna controller, which is basically an XBox 360 work-alike. So I am relatively helpless to figure out LMB and RMB or something else, since I am playing using a keyboard and mouse.

I suspect I have a legitimate complaint here, since this is not developer-intended or developer-level.

In the case of an open-source project oriented to developers and, yes, novices, I agree the API documentation could be improved. Just remember you're criticizing free labor that you can repay in kind. (I paid cash for the game I'm talking about.)

If that's not aligned with your own needs, and you admire the SDL2 documentation, why not just invest there for what you want to be doing?

[leowribeiro]

Dear Orcmid,
thank you for the response, I understand.
You asked : 'If that's not aligned with your own needs, and you admire the SDL2 documentation, why not just invest there for what you want to be doing?"
SDL2 was not designed with 3D programming in mind, that's why I like raylib, with it you can do both not having to "mix" different libraries.

[1NEGROUP]

I concur with @leowribeiro as the CheatSheet is Not Documentation, and some of the examples do not suffice. I am very new to C++ and came from unity, and since unity screwed us, I decided to turn to c++ and Raylib as I thought it would be great for a beginner, and it is for the most part, however even when looking at the .h raylib file I am still kinda of confused as to how i can use functions. For example i was looking the Ray struct that takes has a vector3 position and Normalized. How am i supposed to write it, Does it take both Vectors or only one of your choosing.
I tried looking at Youtube and the examples and found nothing. This is a bit Irritating as I don't want to have to go to the internet to ask about something that others would consider so simple or have to wait for an answer or maybe not even get one at all.

[Peter0x44]

@1NEGROUP the ray struct has no member called "normalized", or anything related.

// Ray, ray for raycasting
typedef struct Ray {
    Vector3 position;       // Ray position (origin)
    Vector3 direction;      // Ray direction
} Ray;

I suspect you're talking about "RayCollision"

// RayCollision, ray hit information
typedef struct RayCollision {
    bool hit;               // Did the ray hit something?
    float distance;         // Distance to the nearest hit
    Vector3 point;          // Point of the nearest hit
    Vector3 normal;         // Surface normal of hit
} RayCollision;

Perhaps confusing if you don't know what a surface normal is, but it's definitely not ambiguous

[Boyfinn]

@1NEGROUP I completely understand and while I agree that not all of Raylib's features are documented at an equal quality compared to most features, and while unity's documentation has been lax in the recent years, I feel like unity's above and beyond quality and quantity of documentation has set expectations a bit too high for people on what level of documentation is acceptable. So far if I've had any trouble understanding the library or found inconsistencies in the documentation, I just ask or let the people here know and find a solution in no time.