Doxygen Style of cocos2d-x¶

• Doxygen Style of cocos2d-x
  • Functions
  • Functions Group
  • Adding Sample Code
  • Comment

We use doxygen to generate API references

Functions¶

 1/**
 2 * Creates a sprite with a texture and a rect.
 3 *
 4 * After creation, the offset will be (0,0).
 5 *
 6 * @param   pTexture    A pointer to an existing CCTexture2D object.
 7 *                      You can use a CCTexture2D object for many sprites.
 8 * @param   rect        Only the contents inside the rect of this texture will be applied for this sprite.
 9 * @return  A valid sprite object that is marked as autoreleased.
10 */
11static CCSprite* createWithTexture(CCTexture2D *pTexture, const CCRect& rect);

It should involves these parts:

• A brief of this function, in this sample, "Creates a sprite with a texture and a rect" is the brief.
• Function description, "After creation, ... will be (0,0)" is the description
• parameter description via @param mark
• return value description via @return mark

Functions Group¶

There maybe a long long list of functions in one class, e.g., CCSprite. In this case, we can organize functions into groups

1/// @{
2/// @name Functions inherited from CCTextureProtocol
3virtual void setTexture(CCTexture2D *texture);
4virtual CCTexture2D* getTexture(void);
5inline void setBlendFunc(ccBlendFunc blendFunc) { m_sBlendFunc = blendFunc; }
6inline ccBlendFunc getBlendFunc(void) { return m_sBlendFunc; }
7/// @}

A group starts from

@{

and ends on

@}

. We should add a name for this group via @name mark.

Note that inherited methods will "fetch" the doxygen comments from parent class automatically. So we don't need to comment these methods that are inherited from CCTextureProtocol.

Adding Sample Code¶

@code

and

@endcode

work for this.
Here's an example:

 1/**
 2 * Sets the batch node to sprite. It's for internal usage.
 3 *
 4 * @warning This method is not recommended for game developers. Sample code for using batch node
 5 * @code
 6 * CCSpriteBatchNode *batch = CCSpriteBatchNode::create("Images/grossini_dance_atlas.png", 15);
 7 * CCSprite *sprite = CCSprite::createWithTexture(batch->getTexture(), CCRectMake(0, 0, 57, 57));
 8 * batch->addChild(sprite);
 9 * layer->addChild(batch);
10 * @endcode
11 */
12virtual void setBatchNode(CCSpriteBatchNode *pobSpriteBatchNode);