Doxygen, Documentation and HACKS!

TrinityCore Development TrinityCore Code Discussion
1

For far too long TC has been stuck in a bit of a rut, We need more documentation but we havent really worked on that idea. We tried recruiting documentation team but it didnt work out well. We also picked as one of our principles an idea that we will NEVER allow hacks into the core code and for the most part we have stuck to that principle. But the result of that is we have had issues languishing in our tracker for years now. we have had broken pieces of code floating about for years. How long can we continue like that. the reason we are low on manpower is because we are a niche project AND we have almost no documentation to our code. Its about time we change that.

Enter doxygen , we have been using it more or less on auto pilot so far. while it is helpful as such I think we arent using it to its fullest potential by far! we can do MUCH better. the tagging and description system in it is simple yet elaborate at the same time while beautifully elegant to use (for our purposes). I am proposing that we document every file, function, member that we can, over time. when people look at our code they know exactly what everything does and how it works. and if they look at the doxygen we should have enough documentation to make a librarian nervous!

This will go not just towards the readability of the code but might even get us more coders and people sending pull requests our way! PS for everyone who submits code or data or a PR, we love you /emoticons/default_smile.png you are awesome!

More about doxygen below, now whats this about hacks? well i think the word hacks is thrown around a lot, sometimes without cause or out of lack of understanding the basics of working on a project like TC. Sometimes things need workarounds. and TC can use these workarounds. so here as of today im making a distinction, there are hacks and there are temporary workarounds. When there is no other way to fix things we WILL use temporary workarounds, and will mark them as such in doxygen using custom tags. so they will always be there for us to view and fix at a later point. this will get us more working parts of the core and will give us a better testing base so maybe the workarounds can be fixed and done properly.

Not everyone will agree with the above and I understand that.Give us your reasons and alternatives, telling us you hate the idea doesn’t mean anything without an alternative.

Here’s a copy of our chatlog regarding this subject: chat_trinity_083112.txt

Working with doxygen is easy, its so easy a caveman could do it! (sorry geico please dont sue us /emoticons/default_sad.png )

Trinity Doxygen Documentation Standards

these will be followed across all TC code.

function documentation (brief)

/// Sets an UPDATE_FIELD, for a float value
void SetFloatValue(uint16 index, float value);
/// Sets an UPDATE_FIELD, for a byte value
void SetByteValue(uint16 index, uint8 offset, uint8 value);
/// Sets an UPDATE_FIELD, for a short int value
void SetUInt16Value(uint16 index, uint8 offset, uint16 value);

function documentation (extended)

/**

  • @brief Tries to find a GameObject given an entry and a range
  • This function searches for a GameObject in place and returns
  • the closest one, if found.
  • @param entry GameObject entry to find
  • @param range The range around the caller the search will be done
  • @return A GameObject* if found, NULL otherwise
  • Example Usage:
  • @code
  • if (GameObject* cage = me->FindNearestGameObject(1234, 10.0f))
  • cage->SetGoState(GO_STATE_ACTIVE);
  • @endcode
    /
    GameObject     FindNearestGameObject(uint32 entry, float range) const;

/**

  • @brief Returns the template of the item
  • This function returns the template of an item, which was taken
  • from the DB and loaded at startup.
  • @return An ItemTemplate const*
  • Example Usage:
  • @code
  • if (Item* item = GetItemByPos(NULL_BAG, NULL_SLOT))
  • ItemTemplate const* proto = item->GetTemplate();
  • @endcode
    /
    ItemTemplate const     GetTemplate() const;

file documentation

/**

  • @file cs_account.cpp
  • @brief .account related commands
  • This file contains the CommandScripts for all
  • account sub-commands
    */

class member documentation

private:
uint32 m_InstanceId; ///< in map copy with instance id
uint32 m_phaseMask; ///< in area phase state

tagging (anywhere)

else /// No more vacant places
{
/// @todo Send a packet to announce it to player
m_PlayersWillBeKick[player->GetTeamId()][player->GetGUID()] = time(NULL) + 10;
InvitePlayerToQueue(player);
}

…

/// @workaround We do not know what types of stealth should be interrupted by CC
if ((m_spellInfo->AttributesCu & SPELL_ATTR0_CU_AURA_CC) && unit->IsControlledByPlayer())
unit->RemoveAurasByType(SPELL_AURA_MOD_STEALTH);

Useful links

Doxygen
Doxygen

2

Thanks for this initiative KingPin. I hope you guys will contribute to Doxygen as much as possible /emoticons/default_smile.png

3

There will be a follow up post with a standard way we will tag our code. The above are just examples of what is possible with doxygen.

4

KP, i can’t watch chat log:(

5

for those not being able to see the attachment :

[paste=‘hvoubgmu84f’]

6

my nipples

(Couldn’t resist, apologies)

7

first post updated with TC doxygen documentation standards.

8

Nice!!!

9

Our doxygen updated with massively awesome new graphs visually representing how each class, member, include is called or calls something or is included. check it out : http://docs.trinitycore.info/

10

Very good! Thanks!

11

remember guys this new system is directly in the repo. make pull requests putting in comments and get your name in the commit log! its like a lottery EVERYONE WINS! o.0

12

I’ve been browsing the source for about two months now. I think the code is decent and additional documentation does little to help an experienced developer figure things out. Good class names: check, good varible names: check, good physical file structure: check.

Any project of sufficient size is hard to navigate with or without documentation. If I have to spend more time sifting through the documentation than the code itself then it really didn’t help all that much.

My two cents: concentrate on the why and architecture choices instead of what a function does. The code is already clear enough to see what many if not most functions do.

Example: Right now I’m digging through code that creates trainer spell lists to send to the client. The mechanics of putting the list together and sending them to the socket is easy to see and figure out. The hard part is figuring out the impedence mismatches between client and server. Why can I send modified spell list to the client, even though the client only displays partial results? I’m not asking directly, I’ll figure it out on my own. My point is that documentation is more helpful if it centers on the why and not so much the how.

Good job though, I hope you keep the good stuff coming.

13

That is exactly why we are doing this, to help newcomers.

14

Thanks KingPin. Trinity is in dire need of documentation.

@Edok Rekam - Yes, documentation can inhibit development when you have to sift through 100 lines of comments just to find 1 line of code. On the other hand, a simple one line comment can go far for explaining the basics of a function, loop, switch statement or anything. This is what Trinity severely lacks. I usually toss in a comment in things that I patch but in most functions there is no commenting at all.

I consider myself an advanced coder but there are still systems in Trinity that I don’t understand and without documentation I find it takes me too much time to properly figure it out. When I sit down to write a patch, I don’t want to spend 5 hours learning a function and 10 minutes fixing it.

@Subv - Exactly, couldn’t agree more. Newcomers who shy away from coding may actually take a chance.

15

I appreciate the feedback, and its good to know you can navigate through the code with relative ease. having a good IDE can circumvent some of the issues not having good comments presents, but thats not always available or sometimes it still isnt enough. Especially for new people who want to delve into the code but are just overwhelmed by looking at the sheer size of it. This commenting will help with that aspect and if you look at the doxygen site the graphs and just the general way its all interlinked can be very useful for a reference.