[Suggestion] Full C++ Source Code Documentation

[xTravax]

Hello

I would like to propose an idea. My idea is that MTA's full source code gets documented on Wiki. It might be a hard job to document everything, but there's no rush, it could go little by little until someday the whole source code is explained on wiki. Also there could be an introduction page where is explained how to compile mta by yourself, and how to do your first function, and so on (Similar how scripting introduction page explains Lua scripting)

The reason why I'm proposing this idea is because contributing to MTA's codebase seems a bit too hard, and not very explained in my opinion, especially for the newer people who'd like to contribute. Simply put, even by reading source code itself, sometimes we don't know what something does even if it's commented in the code.

I think that by achieving this idea we could get people into easier understanding how everything works and how to contribute since everything would be explained on Wiki. This would equal more pull requests,bigger and faster progress, and perhaps some more developers in mta team haha. 

P.S Writing everything on Wiki might take a long time, but throughout say a year I think it could be fully documented (It wouldn't be just 1 guy writing wiki pages, anyone who knows the functions and how they operate could help out by writing a wiki page, hell I'd even help out make the pages, a dev would just need to explain to me how a function works and I'd make the page if they don't have time do so)

Thank you for reading, please tell me what you think of this

[Jusonex]

To start off with some good news: There is already a pretty detailed compile guide: https://wiki.multitheftauto.com/wiki/Compiling_MTASA
Also, we started documenting some parts in the past:

• https://wiki.multitheftauto.com/wiki/Category:Classes_(Blue)
• https://wiki.multitheftauto.com/wiki/Coding_guidelines
• https://wiki.multitheftauto.com/wiki/Coding_info
• https://wiki.multitheftauto.com/wiki/Category:Development

And now the bad news:
The cost of documenting everything is too high compared to the resulting benefit. For most things, there are enough examples, i.e. when implementing a Lua function just string-search for an existing Lua function and copy&paste that code. This approach works fine for the most high-level code. In the lower-level modules (especially Game SA and Multiplayer SA) the explained approach doesn't work very well.
But to be honest with you: We don't understand some parts of that code either due to its lack of documentation without reverse engineering it again. Documenting at least parts of that stuff is absolutely needed, but as it just works atm, our approach is to don't touch the running system.

However, I could imagine documenting some "basic patterns" like "How to implement a Lua function" or general guides like "How to learn reverse engineering for MTA".

[xTravax]

Good to hear that there is already pretty enough documentation to get started. I've checked the source code for a bit, and found out like I thought that there are lots of files e.g related to animations, but you can't really guess which one does what just from looking at names, you need to take a look on the code as well to get more into it. It would be cool though if at least some important files which are big or are constantly used if they at least could be documented on Wiki since there are thousands of files back there. If someone did a little youtube series on coding for MTA that might even be easier than writing all those Wiki pages haha.
 

4 hours ago, Jusonex said:

However, I could imagine documenting some "basic patterns" like "How to implement a Lua function" or general guides like "How to learn reverse engineering for MTA".

Definitely. Youtube came to my mind as I was writing this post, it might be even easier to do than create/code all those Wiki images. Some dev(s) when they get time could record at least basic stuff, how to compile, how to make your own Lua function in C++, and so on, it doesn't need to go into huge detail or series, but at least the basics, if the dev who records the videos wants to make more videos that's even better since people will more easily understand how stuff works. This youtube idea is like when you want to learn a new language and you start watching tutorials on that language, basically like that.

I know my idea might be or sound exhausting but I just think that if this idea was partially or fully did one day, that in the future it would help out people who would like to contribute to MTA, and that is what I would like to see, more contributors, even I would like to learn how to contribute but it's a bit hard to start as I mentioned earlier

Thank you for replying to my topic, if you want to say anything more related to this topic, feel free to do so as I'm interested what you guys back at MTA Team think of this

[pa3ck]

I definitely agree, this is an open-source project, having a reasonably detailed guide / documentation would help attract new contributors. Although, I think it shouldn't necessary be the "Godfathers" job to make such guides, I'm not sure how many contributors are there right now, but if people who already code bits and pieces could also write down how they started, explanation of the structure of the code etc. and then these guides could be accepted by more experienced devs, the "Godfathers". That'd be pretty cool.

[Arran]

As I post this there are 17 open pull requests. MTA developers shouldn't waste time documenting stuff when there's open pull requests made by people who didn't need any documentation that need adding. Even I managed to make a pull request and have made some other contributions in the past and I did that with existing documentation and with only very basic C++ knowledge, a lot can be done by just looking at, copying, modifying existing code.

I Just realised my pull request has been ignored for 5 months even though developers already gave me tips to improve it and I did all the improvements, the code is flawless but un-added it's really demotivating, I'd probably have contributed more if my source patches had have been added sooner and perhaps other potential contributors are getting put off too because why would you spend time making a second patch when your first one might never even get added?

Edited May 13, 2017 by Arran

[xTravax]

24 minutes ago, Arran said:

MTA developers shouldn't waste time documenting stuff

I was just waiting for someone to say this.

"We are MTA Team, we have a huge ego, you should oblige us, screw you if you have requests, your request can be done in a very harder way, so why should MTA Team make it easier for you?" - This is exact thing what you're portraying right now. If you'd have read my post, you'd have seen that I've said that it could be done over time, not instantly right now. Throughout time file by file, or document by document could be documented. Those 17 pull requests are mostly sitting there, some of them get included over time. There would be way more pull requests if there was more documentation about the code. Right now, to become good at contributing what you'd have to do is spend few months learning, testing, experimenting how everything works, all by yourself, and probably wait for hours/days/weeks for someone to even reply to you how to do certain thing to code when you have no idea how to accomplish something. Even with Discord this takes that long.

What do you have now, like 3-4 contributors and 2-3 MTA Staff members working on code, you really find that number of people to be so great? With bigger documentation that number would easily be able to increase, perhaps even to 20-30. This game might be old as well but it's still being played by a lot of people, and more contributors could mean that complex stuff such as custom animations, custom IDs and such could be much easily and faster implemented. I'm waiting for someone's reply which will say how I'm wrong and that it's just a waste of time (again).

[-ffs-Sniper]

3 hours ago, xTravax said:

What do you have now, like 3-4 contributors and 2-3 MTA Staff members working on code, you really find that number of people to be so great?

While MTA might "only" have about 3-4 active developers left nowadays, it used to have a lot more than that during its existence for almost 10 years (even more when considering MTA: Race predecessor). Most of them just aren't around anymore and left development without any significant code documentation. Those who joined later definitely cannot be blamed for lack of documentation neither can they be held responsible/forced to start creating a massive documentation at this point. 

Implying MTA contributors are egoistic dickheads because Arran rejected your point is a very unfair thing to say - especially considering how this project is totally non-profit and yet requires almost full-time care by those who still are active to at least keep this thing stable, pretty much free of cheaters (kudos to ccw) and somewhat developing. MTA is and never was a super-organized project with massive organizations/foundations coordinating development like most open source projects in the Unix universe. If there are no resources available to create extensive documentation on MTA's source code over time then so be it. It is everyone's noble dream to one day create decent documentation but it is simply unreasonable with the current set of resources (apart from some basic guides on adding Lua functions or RE as stated by Jusonex).

Question is: Why don't you take the chance and hook yourself up into this project to try solve the problem of documentation instead of complaining about well-known and obvious issues? In the end everyone involved nowadays had to work his way into this project from zero.

Edited May 14, 2017 by -ffs-Sniper

[xTravax]

I have no idea what the hell is your problem, I see you've barely read my posts, you probably just read some sentences and took them out of context to look bad.

6 hours ago, -ffs-Sniper said:

Those who joined later definitely cannot be blamed for lack of documentation neither can they be held responsible/forced to start creating a massive documentation at this point.

Where did I blame MTA Developers for lack of documentation, or even forced them to do any massive documentation? I have suggested that anyone could contribute to making documentation of MTA code, they don't have to be from MTA Team, they could be even random people.

6 hours ago, -ffs-Sniper said:

Implying MTA contributors are egoistic dickheads because Arran rejected your point is a very unfair thing to say - especially considering how this project is totally non-profit and yet requires almost full-time care by those who still are active to at least keep this thing stable, pretty much free of cheaters (kudos to ccw) and somewhat developing.

I didn't say that they are egoistick dickheads, I said that Arran portrayed them that way, because many requests get denied just because they can be done by someone else or because they don't have time for it. I understand how much current active MTA Developers work to keep this project up to date, and also MTA Contributors. I have no idea where you're getting information that I'm not respecting their work.

6 hours ago, -ffs-Sniper said:

Question is: Why don't you take the chance and hook yourself up into this project to try solve the problem of documentation instead of complaining about well-known and obvious issues? In the end everyone involved nowadays had to work his way into this project from zero.

Because it's really hard to get to know a code which isn't really too well documented, hence the reason why I made this topic in first place. I don't want documentation so just I could selfishly know how to code for MTA, I want the documentation so that everyone can get into contributing without spending months of testing and trying to understand how everything works in there since functions aren't really documented.

Also, since you're so clearly bad at reading, keep in mind that I'm not making anyone to do this instantly, or forcing MTA Team to do this. I am suggesting that MTA code gets documented over time by any person. Function by function for instance, after a year or so the documentation could reach the half of MTA code perhaps, or even whole code, and make it easier for other people to learn how to contribute faster. With proper documentation, getting ready to contribute to MTA could take weeks or even days to learn, and at moment it takes months because of lack of documentation, and even after few months of testing and stuff, you still know very little. By this topic I am encouraging people to help out this project by documenting it, so that we would have more contributors in advance. I am not forcing anyone to do it.

[Arran]

10 hours ago, xTravax said:

I was just waiting for someone to say this.

"We are MTA Team, we have a huge ego, you should oblige us, screw you if you have requests, your request can be done in a very harder way, so why should MTA Team make it easier for you?" - This is exact thing what you're portraying right now. If you'd have read my post, you'd have seen that I've said that it could be done over time, not instantly right now. Throughout time file by file, or document by document could be documented. Those 17 pull requests are mostly sitting there, some of them get included over time. There would be way more pull requests if there was more documentation about the code. Right now, to become good at contributing what you'd have to do is spend few months learning, testing, experimenting how everything works, all by yourself, and probably wait for hours/days/weeks for someone to even reply to you how to do certain thing to code when you have no idea how to accomplish something. Even with Discord this takes that long.

What do you have now, like 3-4 contributors and 2-3 MTA Staff members working on code, you really find that number of people to be so great? With bigger documentation that number would easily be able to increase, perhaps even to 20-30. This game might be old as well but it's still being played by a lot of people, and more contributors could mean that complex stuff such as custom animations, custom IDs and such could be much easily and faster implemented. I'm waiting for someone's reply which will say how I'm wrong and that it's just a waste of time (again).

MTA is open source... What is stopping YOU from documenting this stuff?

Here's some documentation: https://wiki.multitheftauto.com/wiki/Coding_info

And guess who wrote that page? I did. Am I an MTA developer? No. I have managed to make documentation and contribute actual working source patches yet the C++ knowledge that I have could be learned within 1 day so what is your excuse for not looking at the source code and documenting it? Because you didn't make that source code? And you really think whoever wrote that is even around now to document it or anyone can even remember what exactly was written by who when some of this source is 10 years old?

[xTravax]

5 minutes ago, Arran said:

MTA is open source... What is stopping YOU from documenting this stuff?

Here's some documentation: https://wiki.multitheftauto.com/wiki/Coding_info

And guess who wrote that page? I did. Am I an MTA developer? No. I have managed to make documentation and contribute actual working source patches yet the C++ knowledge that I have could be learned within 1 day so what is your excuse for not looking at the source code and documenting it? Because you didn't make that source code? And you really think whoever wrote that is even around now to document it or anyone can even remember what exactly was written by who when some of this source is 10 years old?

What is stopping me from documenting this stuff? Lack of knowledge perhaps? Great, so you did some documentation back there, that's pretty great, so since you feel proud for doing that page, why don't you document more stuff then? (Uh please don't get this sentence like I'm trying to personally fight with you, I'm not).
The people who currently work/contribute to the project certaintly know lot of code of it what it does, or what it probably does, it's easier for someone who already has the knowledge to document a function, rather than telling someone of zero knowledge of it like me to do it.

I am wondering if you guys are just trying to cause a fight in here to get this topic and idea thrown away just because you consider me some selfish bastard who wants other people to do stuff for me, while I'm not doing that, but I'm rather suggesting this topic idea to everyone so everyone could contribute.

[Arran]

Is it just existing MTA internal functions that you want documenting? I thought that visual studio already has features which show you function lists and their parameters. The main thing that stopped me being able to contribute more was when it comes to doing something new, I wouldn't have the slightest clue where to start so for me the most useful documentation would be explaining how to do new things which I guess involves memory hacks.

Like you said, this is something that is done over the long term so there's no reason why you can't get the ball rolling by getting a list of all functions and there parameters and starting some wiki pages with this basic information and then include stuff like "Please can a developer who understands this explain this" and then eventually some information might get added to it.

[xTravax]

1 hour ago, Arran said:

Is it just existing MTA internal functions that you want documenting? I thought that visual studio already has features which show you function lists and their parameters. The main thing that stopped me being able to contribute more was when it comes to doing something new, I wouldn't have the slightest clue where to start so for me the most useful documentation would be explaining how to do new things which I guess involves memory hacks.

Like you said, this is something that is done over the long term so there's no reason why you can't get the ball rolling by getting a list of all functions and there parameters and starting some wiki pages with this basic information and then include stuff like "Please can a developer who understands this explain this" and then eventually some information might get added to it.

Yes, you're right about this. I completely forgot about it. If i want an idea to get going, I should contribute as well. I'll take your idea of grabbing function names and their parameters to at least start the base of documenting the MTA code

I just have to figure out how everything works on Wiki, to not mess it up. I'll post updates here when I add some stuff to Wiki.

[xTravax]

Hi there, I did a page documentation of one cpp file with it's 15 functions, what do you think, is it good?

CAdditionalVertexStreamManager

[Arran]

10 minutes ago, xTravax said:

Hi there, I did a page documentation of one cpp file with it's 15 functions, what do you think, is it good?

CAdditionalVertexStreamManager

Awesome. It just needs a main page for these different files. Then someone with access to edit MTA wiki home page can add a link to it.

[Jusonex]

It's fantastic that you started documenting the code.

But let me state a few things before you invest too much time:
Generally, code snippets in documentation are very good. However, adding the full code of a function will cause inconsistencies between code and documentation sooner or later. Furthermore, it's not necessary to add the path to the documentation as it can be found using Visual Studio's "search in all projects" feature.

Consequently, I'd prefer inline documentation (comment blocks in the code) over manually-written wiki documentation. An online documentation can be generated with the help of Doxygen later. Another adavantage of using inline documentation is that you don't have to look the documentation up in the wiki while browsing the code (there's some inline documentation already btw: https://github.com/multitheftauto/mtasa-blue/blob/master/Client/core/Graphics/CRenderItemManager.cpp#L414-L421).

In general however, I think documenting the idea behind certain source parts is much more important than documenting single functions, because knowing what each function does doesn't necessarily make you able to implement your feature - as only the sequence of multiple functions does the trick in many cases (single functions in C++ often do less compared to Lua - so the general workflow differs). For example when you're working with the CAdditionVertexManager you documented, you won't be able to use the methods at all without having knowledge about how vertices are handled by the renderer. If you know that, you're already able to deduce the description from the function name.

And now, I'm very sorry to confirm your critisism about wasting time: Effectively, we're only a handful of active developers and it's not arguable that documenting the existing code is a very time-consuming task. In consequence, it only makes sense for us to start documenting extensively, if the resulting benefit is big enough. In my opinion, it isn't as the number of additional developers we'd address is very small, because experienced C++-developers don't need "single-function-documentation" that much.