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 )
these will be followed across all TC code.
/// 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);
- @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:
- if (GameObject* cage = me->FindNearestGameObject(1234, 10.0f))
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:
- if (Item* item = GetItemByPos(NULL_BAG, NULL_SLOT))
ItemTemplate const* proto = item->GetTemplate();
ItemTemplate const GetTemplate() const;
- @file cs_account.cpp
- @brief .account related commands
- This file contains the CommandScripts for all
- account sub-commands
uint32 m_InstanceId; ///< in map copy with instance id
uint32 m_phaseMask; ///< in area phase state
else /// No more vacant places
/// @todo Send a packet to announce it to player
m_PlayersWillBeKick[player->GetTeamId()][player->GetGUID()] = time(NULL) + 10;
/// @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())