Doxygen support

Donik · 03-27-2013 05:01 PM

I'm used to document all my code very thoroughly (some might say i overdo it ^^). For that purpose i like to use Doxygen, but i encountered a small problem. Comments above a class are not recognized by Doxygen, due to the way the Code Editor translates to C++ code. To make it clear, here is an example:

Code:

//============================================================================

/** \file FSMState.h

 *

 *  \brief This file includes the FSMState class which can be used as a basis

 *         for more sophisticated states.

 * 

 *  \author Donik

 * 

 *  \date Mar-18-2013: Created this file

 *

 *  \todo

 *

 *  \bug

 *

 *  \version 1.0

 ****************************************************************************/

//============================================================================

// N A M E S P A C E

//============================================================================

/// The Namespace of Utility classes and functions

namespace UTILS

{

//============================================================================

// C L A S S 

//============================================================================

//============================================================================

/** \brief Base class for all types of entity states the game has.

 *  

 *  \author Donik

 *

 *  \date Mar-18-2013: Started implementation

 *

 *  \version 1.0

 ****************************************************************************/

T1(state_type)

class FSMState

{

public:

   //=========================================================================

   // P U B L I C   M E T H O D S

   //=========================================================================

   //=========================================================================

   /** \brief Empty standard constructor.

    *

    *  \version 1.0

    *************************************************************************/

   FSMState() {}

   //=========================================================================

   /** \brief Virtual empty standard destructor.

    *

    *  \version 1.0

    *************************************************************************/

   virtual ~FSMState() {}

   //=========================================================================

   /** \brief Called once when this state is entered.

    *

    *  Doesn't need to be called from derived classes, the corresponding FSM 

    *  class will take care of that.

    *

    *  \version 1.0

    *************************************************************************/

   virtual void OnEnter(state_type*) = 0;

   //=========================================================================

   /** \brief Called whenever the state needs to be updated.

    *

    *  Doesn't need to be called from derived classes, the corresponding FSM 

    *  class will take care of that.

    *

    *  \version 1.0

    *************************************************************************/

   virtual void OnUpdate(state_type*) = 0;

   //=========================================================================

   /** \brief Called whenever the state needs to be drawn.

    *

    *  Doesn't need to be called from derived classes, the corresponding FSM 

    *  class will take care of that.

    *

    *  \version 1.0

    *************************************************************************/

   virtual void OnDraw(state_type*) = 0;

   //=========================================================================

   /** \brief Called once when the state gets changed to another one.

    *

    *  Doesn't need to be called from derived classes, the corresponding FSM 

    *  class will take care of that.

    *

    *  \version 1.0

    *************************************************************************/

   virtual void OnExit(state_type*) = 0;

}; // End of class: FSMState

} // End of namespace: UTILS

Everything except the comment above the class works as expected.
There are two solutions i could live with:
1) Make it so that the translated C++ code keeps the class comment in the right place.
2) Give us the possibility to export the code files from the code editor to some text format. Even .txt would be just fine. That way i could run doxygen on these exported files and everything would work.

Thanks for considering wink

JonathonA · 03-28-2013 04:04 PM

I second that. As much as there are comments in the code, formal documentation would make finding code you want much easier and it will be far easier to see the structure of the engine. Not only that, but considering that when we sometimes have problems using the Esenthel Engine and the community here is limited with its responses (e.g. 'look at comments') more formal documentation would be excellent.

Donik · 03-28-2013 04:39 PM

Well i'm not suggesting that Esenthel uses Doxygen for comments, i want to be able to use it myself. Of course it would be nice if Esenthel would use Doxygen in it's headers, but thats not what i was asking for.

All i need is an export function for the code files directly from Code Editor, so i can run Doxygen on them. At the moment i literally have to copy paste each of my code files to external files and run doxygen on them...

uNetti · 03-30-2013 04:04 PM

Why not click the open in visual studio (Default:F8)?
It should be possible to run doxygen on Esenthel 2.0\Projects\_Build_\yourproject?

Scarlet Thread · 03-30-2013 04:38 PM

(03-30-2013 04:04 PM)uNetti Wrote: Why not click the open in visual studio (Default:F8)?
It should be possible to run doxygen on Esenthel 2.0\Projects\_Build_\yourproject?

This doesn't work because, when Esenthel is formatting the .cpp files, it moves the comments and classes around and puts them out of context.

Donik · 03-30-2013 05:56 PM

Scarlet Thread is right. This is exactly the point i was trying to make in my first post. Everything works, except the comments above a class.

gwald · 03-30-2013 10:51 PM

Agree, It is a serious bug/issue.

Donik · 03-30-2013 11:03 PM

(03-30-2013 10:51 PM)gwald Wrote: Agree, It is a serious bug/issue.

Do i smell sarcasm here? grin

I know it's not a serious issue, but it's something that could be fixed pretty easily i assume.

gwald · 03-31-2013 01:00 AM

no, not sarcasm!

It's serious because it is the only way in v2 editor to access our code!
And EE is moving comments (and other things), which I understand is necessary but a pain.

Not just for Doxygen, but revision control, printing, zipping and sharing etc etc.

The editor is nice but not having access to (exact) code is a pain :(

Feature request: Can I suggest when you build, it creates another folder called src which has the EE v2 editor app source files? IE: exporting .es src automatically

Donik · 03-31-2013 04:55 PM

(03-31-2013 01:00 AM)gwald Wrote: Feature request: Can I suggest when you build, it creates another folder called src which has the EE v2 editor app source files? IE: exporting .es src automatically

I really hate to be annoying, but it would be really nice to have a statement on that from Esenthel himself... =)

**Esenthel** · 04-02-2013 07:05 PM

next release will copy this part of codes

Code:

//============================================================================

 // C L A S S 

 //============================================================================

 //============================================================================

 /** \brief Base class for all types of entity states the game has.

 *  

 *  \author Donik

 *

 *  \date Mar-18-2013: Started implementation

 *

 *  \version 1.0

 ****************************************************************************/

before the class declaration in its header

JonathonA · 04-02-2013 09:30 PM

Does that mean you will be using the doxygen syntax on all class comments in the engine source Greg? smile

**Esenthel** · 04-02-2013 10:29 PM

Hello.
No, I've only given an example that Code Editor when generating C++ files will copy the comments located before the class, to the header as well (this is what's this thread about).

Donik · 04-03-2013 07:32 AM

Thats exactly what i want, thank you soo much!

Doxygen support
Author	Message