Standardizing Source Documentation and Code

[Akinari]

In 9744ba4 I made the first update to what will be a series of updates to our source to standardize and document all functions and other things that are deemed important for both developers and aspiring hackers.  We hope this ends up being a tool to help the standard user figure out what the functions are doing.  We've had Doxygen available on the site, but no one ever decided to standardize code for it, so it just became an outdated, unused, unhelpful tool.  We are aiming to change that by making everything be pulled into Doxygen, once it gets updated and pointed to GIT.

 

So let me post some of the basics here as far as what we, the Core Development team, have decided upon.

 

• All documentation should have proper grammar and be understandable to degree
• All functions shall have standardized documentation directly above the function header (see below and file)
• Documentation shall not be nothing but a credit (IE: // [Akinari])
• All documented code shall follow these comment standards
  • '///' Is a Doxygen comment for one line
  • '///<' Used for variable declaration commenting
  • '/** **/' Standard function documentation
  • '//!' For TODO and FIXME
  • '//' Regular comment not shown in Doxygen

Over the course of the next few weeks/months that these files are being standardized, it is very likely those with modified source files will run into conflicts.  I highly advise you stay aware of these changes and update according to your time constraints.  In general we attempt to avoid major file changes, but standardization has been held off for far too long.  Occasionally with these file changes we will also do some small optimizations and, while we do test the changes, please know that these can cause new bugs, so report these accordingly.

 

With that being said, I will keep a record as to what files get completed here and update it accordingly.  Thanks for your time and if you have any comments or questions, feel free to post.

status.c [ 9744ba4 ] - There are a few notes and a function or two without documentation, but standardizing it is done

unit.c [ bf7e8ea ]

 

Doxygen link has been updated to: http://rathena.org/doxygen/

[GmOcean]

Yay, finally lol. I've been waiting since eA for the src to be standardized with a form of proper documentation, because unless your familiar with the code and know what your looking for, you're going to get lost and fast. It may be just 1 file atm, but it's one step in the right direction. Keep up the good work.

[Akinari]

Doxygen has now been updated to http://rathena.org/doxygen/

 

We will be setting up cron jobs to take care of rebuilding documentation on a daily basis.  For an example of how a complete file looks, refer to the status.c in the new doxygen link (also available through the Wiki drop down on the top bar).

 

Edit:

Referenced By configuration has been set up so you can see what functions call that one you're currently viewing.

 

Edit2:

Cron jobs set up to automatically update the doxygen page daily.

Updated unit.c in bf7e8ea.