About Store Forum Documentation Contact



Post Reply 
Doxygen support
Author Message
Donik Offline
Member

Post: #1
Doxygen support
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
03-27-2013 05:01 PM
Find all posts by this user Quote this message in a reply
JonathonA Offline
Member

Post: #2
RE: Doxygen support
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.
03-28-2013 04:04 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Donik Offline
Member

Post: #3
RE: Doxygen support
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...
03-28-2013 04:39 PM
Find all posts by this user Quote this message in a reply
uNetti Offline
Member

Post: #4
RE: Doxygen support
Why not click the open in visual studio (Default:F8)?
It should be possible to run doxygen on Esenthel 2.0\Projects\_Build_\yourproject?
03-30-2013 04:04 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Scarlet Thread Offline
Member

Post: #5
RE: Doxygen support
(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.
03-30-2013 04:38 PM
Find all posts by this user Quote this message in a reply
Donik Offline
Member

Post: #6
RE: Doxygen support
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.
03-30-2013 05:56 PM
Find all posts by this user Quote this message in a reply
gwald Offline
Member

Post: #7
RE: Doxygen support
Agree, It is a serious bug/issue.

My Blog
http://www.esenthel.com/community/showthread.php?tid=6043

I hang out at Esenthel IRC Channel
http://webchat.freenode.net/?channels=#Esenthel
03-30-2013 10:51 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Donik Offline
Member

Post: #8
RE: Doxygen support
(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.
03-30-2013 11:03 PM
Find all posts by this user Quote this message in a reply
gwald Offline
Member

Post: #9
RE: Doxygen support
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

My Blog
http://www.esenthel.com/community/showthread.php?tid=6043

I hang out at Esenthel IRC Channel
http://webchat.freenode.net/?channels=#Esenthel
(This post was last modified: 03-31-2013 12:18 PM by gwald.)
03-31-2013 01:00 AM
Visit this user's website Find all posts by this user Quote this message in a reply
Donik Offline
Member

Post: #10
RE: Doxygen support
(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... =)
03-31-2013 04:55 PM
Find all posts by this user Quote this message in a reply
Esenthel Offline
Administrator

Post: #11
RE: Doxygen support
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
04-02-2013 07:05 PM
Find all posts by this user Quote this message in a reply
JonathonA Offline
Member

Post: #12
RE: Doxygen support
Does that mean you will be using the doxygen syntax on all class comments in the engine source Greg? smile
04-02-2013 09:30 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Esenthel Offline
Administrator

Post: #13
RE: Doxygen support
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).
04-02-2013 10:29 PM
Find all posts by this user Quote this message in a reply
Donik Offline
Member

Post: #14
RE: Doxygen support
Thats exactly what i want, thank you soo much!
04-03-2013 07:32 AM
Find all posts by this user Quote this message in a reply
Post Reply