MaNGOS Documentation | A kind of thought about MaNGOS

[shlainn]

but you'll make fun of it

Nope, we'll help you.

[Unkle Nuke]

As a famous actor once said, "Part of being a success is never being afraid to look stupid."

I'd say that applies to any endeavor. Look how people ridiculed the Wright Brothers, or poked fun at that eccentric old guy in Menlo Park, for their crazy ideas.

Everyone has to start someplace. You just begin and worry about the minor details as you go. After all, Edison had no one to teach him!

[Gotisch]

I made some documentation for the mail.cpp mail.h files to test out doxygen and to check out how "documented" mangos code would look. Please tell me your opinion and if its worth it.

Some comments:

1. i used the @params syntax because some other files already where using the @ syntax.

2. Everything is a sentence and thus finishes by a . (this is opinion, maybe do it otherwise?)

3. I tried to comment stuff where it is implemented, not necessarly just mentioned.

Questions are:

What should be documented in header files, what in cpp files? I currently went after commenting everything where the actual code is. so mostly constructor in header methods in cpp. What should we do for this? etc. i think much needs to be answered before documentation can be done, else there will be much need to refracture. and more ...

here is diff of changed files: http://pastebin.com/m183f6d1a

and resulting documentation files can be found here: http://78.47.254.221/tmp/html/group__mailing.html

(its documentation of clean mangos with just the two files edited.)

(edit: i see that i accidently have /*** at 2 items or such so documentation is not generated for those. but you get the idea)

[Toinan67]

Hi Gotish,

Thanks for your participation

I saw this doc was already commited in rev. 9406, good job!

I don't know at all how C/C++ programmers document their code, I'm just giving my opinion :

The general idea would be to follow Doxygen comments structure, as you began to do (@param, @see, @whateveryouwant).

I appreciate the idea of making clear sentences, with a . and "easy" words, for those of us who care not english or english-speaker like me

For header files, no need to add much things, except for methods directly implemented in .h files. Comments should be where we need it, in .cpp files.

More globally, I think a paragraph could be greatly appreciated for each "group" (group "mailing", group "movement", group "items", ...). It could be a sum-up of the whole system, how functions behave together, in what order they are invoked. Example (quite poor I know )

First, we call function 1 to make sure blabla
Then, the message is sent to the function2 for ...
After that, we teleport the player to ...
Finally, we call the last function, function3, to ...

It could be some comments on an algorithm or anything else. As I said, a sum-up on the main behaviors inside the file.

If people wants to learn more on a specific point, they can go straight to the function they want.

That was just my opinion, I'd be glad to see "pros" documenters giving their!