MaNGOS Documentation | A kind of thought about MaNGOS

[Toinan67]

First of all, sorry if this topic has already been discussed, I've made some searches, no answers...

MaNGOS is what I would qualify a weird project. When I began to be interested in it, I didn't know very much in C++ and MMO's servers. I looked the sources, woaw, what a messy code, no commentaries, no explanations, nothing. Quite strange for an educational project...

I'm better in easier scripting langages such as PHP. And PHP projects (for example) have docs, explanations, commentaries, etc. People can understand what is done, and bring their participation to it, or make some modifications. They seem to be organized

MaNGOS does not have any of it, and I still don't know how this project can be alive without it.

Today, I can do some stuff on the core, after months of work and experiments. I believe that with a documentation, it would have been wayyy faster.

You'll say : nobody wants to make a doc. I'll say : nobody CAN make a doc, except half a dozen of genius

Personally, I cannot do it myself. I can help, of course, but there are lots of things I cannot explain.

I'm aware that today, most of MaNGOS users create public servers, and try to make money of it... (that's not a secret).

Therefore, they don't care at all of how it works. Well, you cant do anything against that, but at least we can help the ones who want to understand how it works!

So I propose to create a MaNGOS Doc today. Something which would look like Qt's documentation for those who know it. Explanations for all functions, classes, algorithms...

What's more, I'm sure it would help devs to have a global view of the project, to be organized, to work better and faster.

As I said before, I do not have the knowledge to do it alone, but I can help !

I profit from this thread to congrat all MaNGOS devs (VladimirMangos is the one I see the most, I don't know how many they are ^^). You really do a great job

Have a nice day

[Unkle Nuke]

Such an effort on your part would greatly appreciated by a great many people here. Contrary to appearances, those who take regular part in these forums are indeed here for the sake of learning.

I highly recommend you obtain a download of Doxygen and use it, along with the Doxygen config files in the MaNGOS source tree, to generate the commented documentation of the source code as a starting point. It can help you to sort out the "mess" by showing the relations bewtween modules, libraries, and functions.

[VladimirMangos]

I personally support view point that propertly writen code can be self docummented. Ofc, exist some cases where comments can be need because C++ code itself not let in like places cleary described in short way what done.

As pointed Doxygen can help good for ppl that can't fast extract and see data base just by code.

[Toinan67]

I don't really know Doxygen, but I found one documentation of MaNGOS made with this tool there -> http://amki.kicks-ass.org/doxygens/mangos/

From what I see, that's not really a documentation, but it shows the structure of the project. It doesn't really help a lot...

It may be a starting point, however.

Vladimir, as you said, "properly writen code can be self documented". Do you think MaNGOS has properly written code?

I don't know if you guys have already seen the source code from a big big project, for example PHP-forum source code. For a 1000 lines file, there are 200 lines of commentaries...

I know that's boring and everything, but I'm sure this could help a lot, and bring some "professionalism" to MaNGOS.

That's what we learn first when studying programming : comment your sources, always, even for a 100 lines project.

However, I don't know what's the best way to do it, directly in the source code, or externally with a great documentation.

I may start a non-official doc next days

Greets!

[FragFrog]

I am with Vladimir on this one to be honest. Yes, comments are good and should be used where misunderstandings might arise, but creating a doxygen page really won't help you that much. Just look at the 'game' project directory - it contains (on my version) 257 files, the top of which is over 18.000 lines long - I have no idea whether this is considered normal for C / C++ projects, but if anyone on my old team of webdevelopers tried making a classfile longer than 200 lines he'd better have a damn good explanation during code review time, and that is including comments.

There simply is very, very little factorisation making it next to impossible for a new developer to know just what changing a line might do - it could have no effect, or it could effect any of a thousend, a tenthousand other lines in that class / file. Perhaps seasoned C/C++ developers find it all easy and clear, but to someone used to a clear factorisation in small related groups it looks horrible. Since ScriptDev2 handles its script much better in this regard (a few dozen files per directory max, most sources under three, fourhundred lines of code) I am inclined to believe somewhere far in the past of Mangos development it all went wrong, or maybe the developers simply just like it this way. Either way, document all you want but I fear it is not going to make the source any clearer.

Not meant as an insult to current developers by the way - you guys do an awesome job and I greatly admire how you all always seem to know just where to find a problem and fix it. I just think it's a maintainability nightmare

[xeross155]

I don't mind 18k lines of code in 1 file, but a little info on where to find what, and what everything does is very helpful indeed. I have some understanding of the maildraft class now so I might be able to write something up for that.

1 thing though, if I document it IMO it should be added to the main repo (The comments), I'll of course be using Doxygen format and be as descriptive as possible, and it should be reviewed for correctness of course.

[freghar]

A nice example of what not-so-well documented code can cause .. is trinity project. I've heard rumors about duplicated functions doing the same thing, misusing some of the subsystems, crashes and "hacks", just "because they can't understand the code". A good documentation would help to drastically reduce such things.

However there's no documentation how *something* should be implemented, no publicly-available policy for changing files and adding "hacks", both projects do it the way they like it (because nobody knows how "the other side" does it) - which results in great incompatibilities between both projects. This might be intentional, but I believe it isn't.

[Toinan67]

FragFrog, I totally agree with what you said =>"I am inclined to believe somewhere far in the past of Mangos development it all went wrong". This "game" directory is quite disgusting at the beginning ^^

You say it wouldn't be great to create a doc, but what would you do instead of it? Let it go like that? Maybe it's too late to start something....

As freghar said, this kind of behavior can cause horribles issues like duplicated functions or things like that.

I think we all agree that something must be done, it would be great to hear main actors, which are MaNGOS devs. (I hope Vladimir's not alone! ^^)

[Schmoozerd]

I think what would really be helpful would be a small "api" documentation, that is for each function a line or two what this function actually does, such that startes can get more easily into the code;

and I think there is another good thing about having a documentation done - while documenting one rethinks about the code itself, and this surely is a good thing

[darkstalker]

maybe some javadoc-like documentation for c++

[kero99]

A documentation project where devel and users can participe will be cool.

[DasBlub]

maybe some javadoc-like documentation for c++

you mean doxygen

as said before, code should be self-describing. but still, code documentation would be good. i would suggest to add doxygen to MaNGOS (actually, there is already a config file in /doc/). maybe also a crontab which automatically creates the doxygen and uploads it to getmangos.eu ?

-- DasBlub

[Toinan67]

Well, everyone seem to be interested in Doxygen, so why not including it to the doc/ directory to have a start-point?

Do we have to begin a "non-official" documentation first?

[Unkle Nuke]

There's always the MaNGOS wiki, or something like it, that could serve the purpose of documenting the source quite well. This way, all those who understand parts of the code can contribute until a fully documented source is done by aggregate.

[Toinan67]

"all those who understand parts of the code can contribute until a fully documented source is done by aggregate"

That's what I'd like to see!

But I don't really want to begin with the Wiki, then being tell "well, the wiki is not very good for a documentation, restart with Doxygen", then "well, Doxygen is not the best for documentation, try to comment to the code in the file themselves", etc...

However, I believe the best way to begin is the Wiki as you said, so...let's go?

[FragFrog]

Doxygen extracts comments directly from the code Toinan67, which is partially the reason for its widespread use.

But without structure and organisation in the code itself, doxygen (or any other automated documentation generation process) will not help much - it can build a list of callstacks and class hierarchies, but that by itself is not very usefull, at least, not in my experience. To make the code easier accesable to new developers it should undergo major refactoring, which seeing the size of the codebase is nearly impossible at this point.

[Unkle Nuke]

Refactoring would not be impossible, it's just that the time and effort involved with such an overhaul would bring further core development to a grinding halt for at least 6 months, a year would be more realistic.

Also, having a more tightly structured source tree would place constraints upon more free-from styles of coding and force programmers into adhering to that structure or else you'd wind up with the same undocumented mess in a matter of months. It would require contributors to document their functions as part of the requirements for submission... and we know how much most code hackers hate documenting their work!

On the other hand, having a clean, organized, fully documented source tree would drastically speed up development. It would allow far more people to contribute patches when they're able to make sense of the areas in the source they wish to work upon without devoting hours of study to the whole. Approaching the MaNGOS core as it stands now can be a very daunting task for those unfamiliar with the code base.

Patch submission and review would be more efficient. It would require fewer revisions and fixes on the part of the contributor by having a better understanding of the overall structure that their patch fits into, allowing for cleaner, more correct code right from the moment of initial submission.

[DasBlub]

the time it'd take you to do a refactoring in the mangos code and make it work again is too much. in that time you could as well rewrite the whole code (ofc taking the informations from the other one).

and anyone can add documentation. you can just add doxygen comments to the code and submit it as a patch. i'm sure, it'll be accepted if it's correct

-- DasBlub

[freghar]

I agree the only possible documentation here is doxygen (including warnings what the function shouldn't be used to, point to a better one for that usage, ...). Anything else is just too unreal here ..

[shlainn]

On the other hand, having a clean, organized, fully documented source tree would drastically speed up development. It would allow far more people to contribute patches when they're able to make sense of the areas in the source they wish to work upon without devoting hours of study to the whole. Approaching the MaNGOS core as it stands now can be a very daunting task for those unfamiliar with the code base.

Seeing the under review section of this forum, I honestly cannot believe that too few people are contributing patches. It's just the patch review process takes quite a long while.

IMHO It is definitely not necessary to study the whole codebase to contribute a small local fix to something like a broken spell. If on the other hand someone wants to fix something big, like say, the Vehicles, or some core mechanics, it is impossible to avoid reading the actual code on a global level.

I completely agree with Vladimir on self-documenting code. It takes some getting used to, definitely, but code can't be as misleading as a badly written comment. And if it is, it needs to be rewritten anyway to be more clear - this is something we regularly see in the commits.

So while I think that some kind of introductory stuff explaining what is where and interacts with what to get people started into the code would be useful, a standalone documentation project might be overkilling the problem.

Have a nice day, shlainn

[xeross155]

Well we atleast need a proper documentation on how everything is structured, where one would find certain logic and that kind of thing.

[Toinan67]

I don't really know what choice would be the best here

Self-documenting code is the first thing we think about, that's right. On the other hand, why would nearly every big projects have their own doc? I mean, I'll take Qt (one more time) as an example, the doc is just fabulous. Smaller projects have their doc, too.

Don't you believe it would be a great advantage compared with "ennemies" projects? I don't know how they deal with this "doc" thing, but many people would find MaNGOS easier with a doc. It would definitely add an "aura" around MaNGOS ^^

The problem is that, for now, the code is not self-documented enough. For "learning" developers, like me, it really takes a long time to find what to change, and where to change it. For experimented devs, or devs who work on MaNGOS for some years, I understand it might be quite easy. But even for them, a doc would bring something.

As xeross said, a "structure-documentation" would be the minimum, I think.

[lp-vamp]

Documentation of structue, class and code could be in text and graphic forms. To generate a UML class diagram of the code you can reverse engeneering the code-base. Every class could be introduce with some lines of clear text. Doxygen is a good point for a dictionary where to search names/variables/references within. Entety Relation diagram for the DB-structure, i am sure i've seen some pictures here in the past.

[Unkle Nuke]

There is also software available that can generate those UML diagrams.

I do agree there are many patch submissions but my point is there could be far more. The more people that can understand and contribute to the project, the more robust and resilient MaNGOS will be.

The first step would be in encouraging those who understand the code to begin submitting comments to the commits. That's the most simple and direct method.

The next step would be for those who wish to begin work upon a documentation project with all the bells and whistles to start laying the ground work. Get your outlines, tables, and flowcharts ready then set up a wiki for developers to make contributions.

Others have attempted similar efforts and they died off in a relatively short time. By my experience, precious few ever stick with any project to its completion. I hope you will finally be the scribe that many have wished for, Toinan67!

[Toinan67]

Sorry, but I can't the scribe ^^

I don't have enough knowledge. I can help as I said, but I don't know a lot of things about MaNGOS. I'm a bit desperate with all your comments...I mean, I know it will take a looong time, but why not begin, at least?

Someone should start something alone, then others will join. I can be the "someone"...but you'll make fun of it