API Documentation with AppleDoc

[vlidholt]

UPDATE:

We have chosen to go with AppleDoc. Some things to keep in mind while doing API docs:

• Lars is the boss of documentation, check with him before starting so that no double work is being made!
• Check the CCControl.h file for a reference on how to write the header file.
• VVDocumenter ( https://github.com/onevcat/VVDocumenter-Xcode ) can be a great help while writing the method calls.
• Group the methods logically using the @name – it makes it really neat in the documentation.
• Start sentences with capital letters, end them with a punctuation. (This is currently not the case everywhere in the header files.)
• Use normal comments ( // and /* */ ) in .m files and in the private APIs. Everything that is not in cocos2d.h is considered a private class.
• It may sometimes make sense to rename categories so that they get a good title in the documentation (the names doesn’t make any difference coding wise).
• After documenting a class, run the appledoc target in cocos2d-ios.xcodeproj and preview the class in the generated html-files. Ensure that it looks good.
• Share anything that I might have missed. :)

UPDATE 2: Some more points to take into consideration:

• The old docs are not always very well written, they need to be reviewed and updated where they are out of date. For instance, CCRenderTexture uses the term RenderTexture in many places, this is likely the old name for the class and should either be written as CCRenderTexture or “render texture”.
• Usually no need to add information about which classes the class inherits from or which interfaces are implemented, this is displayed in the documentation anyway.
• All classes should have at least a short description about what they do. Example CCLabelBMFont:

/**
CCLabelBMFont is a subclass of CCSpriteBatchNode
 *Features*

 - Treats each character like a CCSprite.
*/

More descriptive would be:

/**
CCLabelBMFont displays a bitmap font label. The label is loaded from a fnt-file
created with an external editor. Each character in the label is represented by a
CCSprite and can be accessed through the children property.
*/

• For sub-headings in the text use the ### prefix. Example see CCNode:

/**
Even if the positions and content sizes are not set in points you can use actions
to animate the nodes. See the examples and tests for more information on how
to set positions and content sizes, or use SpriteBuilder to easily play around with
the settings. There are also more positioning options available by using
CCLayout and CCLayoutBox.

### Subclassing Notes

A common user pattern in building a Cocos2d game is to subclass CCNode,
add it to a CCScene and override the methods for handling user input.
*/

Old post follows:

I suggest using Appledoc to document the next version of Cocos2d. A big advantage is that it is easy to integrate with Xcode. When documentation is installed, the user can just option click a class/property and get immediate information about how it works, it also shows up in the documentation browser.

More info on Appledoc here: http://gentlebytes.com/appledoc/ and a tutorial here: http://www.cocoanetics.com/2011/11/amazing-apple-like-documentation/

Before we start and split up the work, we need to agree on a common coding and formatting style for the header files.

[slembcke]

Hmm. That's a new one to me. Spent several minutes looking for example output linked somewhere from the page. Apple uses headerdoc, but with a lot of custom styling. The default output is awful. I've used Doxygen in the past and can't really recommend it.

[Panajev]

I think that whichever style is chosen for Cocos2D, we should stick with whatever clang understands and parses best. In order for documentation not to become outdated quickly, I find that letting Xcode spit out warnings for documentation errors very useful.

[web [iPhone msg]]

On 18/ott/2013, at 05:27, slembcke notifications@github.com wrote:

Hmm. That's a new one to me. Spent several minutes looking for example output linked somewhere from the page. Apple uses headerdoc, but with a lot of custom styling. The default output is awful. I've used Doxygen in the past and can't really recommend it.

—
Reply to this email directly or view it on GitHub.

[vlidholt]

I gave Appledoc a quick run, and the output you get is already very useful (but it can certainly be improved with better formatted headers).

[Birkemose]

I use AppleDoc and VVDocumenter.
The later one is invaluable to me, especially in customising various kinds of help comments

I still think it is a disgrace to spam the header with all this. It should go in the implementation.

[slembcke]

Hmm. Sounds like people have really liked AppleDoc then. (still haven't taken the time to try it yet)

Does it really allow you to doc the implementation instead of the header? That sounds mildly attractive. IMO headers should at least have one line descriptions for things, but I do agree that headers are not the place to write a full description. It makes them very hard to use as a reference.

[Birkemose]

Yeah, it allows for the documentation in the implementation.

Docs in the headers, is a "well it is better than nothing" solution, which has then become a standard. It is a disaster, as a slightly commented, well formatted and spaced up header, can give you a one-shot view of what the class will do. Which functions do I have, to create an menuItem with a call back selector? The header is where you should look for that … or of course a dedicated manual, but I do not think we are there yet.

Den Oct 18, 2013 kl. 11:40 PM skrev slembcke notifications@github.com:

Hmm. Sounds like people have really liked AppleDoc then. (still haven't taken the time to try it yet)

Does it really allow you to doc the implementation instead of the header? That sounds mildly attractive. IMO headers should at least have one line descriptions for things, but I do agree that headers are not the place to write a full description. It makes them very hard to use as a reference.

—
Reply to this email directly or view it on GitHub.

[vlidholt]

It is pretty much standard to have the generated API documentation in the header files. What goes in the implementation files should only be documentation related to the specifics of the implementation. There are several reasons for this. For one, the idea with the header file is that you should be able to exchange the implementation without changing anything that is visible from the outside. Also, developers that are using a static library will not be able to look for the docs in the .m files. Also, most people will not look for any documentation in the .m files.

The fine side with adding automated documentation using Appledoc is that you can get your one shot quick overview right in the Xcode docs (or even by option clicking keywords etc).

[vlidholt]

I've now added support for Appledoc on the develop-v3 branch. It's super easy to try out for those who wants. Just open the cocos2d-ios.xcodeproj and select the 'appledoc' target and build. All documentation files (including html) will be generated to the api-docs directory of cocos2d-iphone and the docset should also be installed in Xcode.You may need to restart Xcode to be able to use the new docs.

There are quite a few warnings outputted by Appledoc, but the output still doesn't look super bad. There are some minor changes we may need to do code-wise, like changing typedef enum to use NS_ENUM (which may be a good thing to do either way).

[vlidholt]

Tested to add properly formatted documentation to one of the header files:
https://github.com/cocos2d/cocos2d-iphone/blob/develop-v3/cocos2d-ui/CCControl.h
I think that this format works pretty well, both reading in Xcode, and the documentation looks great! This could serve as a template for how to write the documentation, or do you have any suggestions for how to format it even better?

[vlidholt]

Did an update to the original post!

[Birkemose]

Martin and I will be going over the header files, and update anything we can find.

For now we will coordinate amongst our selves, who is doing what.
If anyone have code they want to document themselves, please let me know.

[Birkemose]

I mentioned this elsewhere, but let me mention it again.
Martin and I talked about removing @SInCE from the documentation. We don't think it makes much sense to have @since0.7.1 in a fresh v3 release.

[vlidholt]

Agreed, I'm all for removing them. As we aren't providing a migration path from v2, maybe we should also take the chance to clear out the deprecated file too.

[dominik-hadl]

+1 for clearing the deprecated file 👍

[cocojoe]

The majority of core cocos2d files are now documented, we are leaving support files for now however there are a few that I think are very useful so will document these, CGPointExtension for example is incredibly useful however judging by the forum, most users don't even know it exists.

Any others?

[cocojoe]

While I'm looking at the current doc warnings, I've tweaked a few and started on CCPhysics however these also need looked at:

CCNode
CCTextureCache
CCDirector
CCColor

[cocojoe]

Have made a pull request for Physics, appledocs now generate with zero warnings which is nice.
@slembcke It would be nice if you could at some point flesh out the descriptions for the different physics classes, I didn't feel I could explain them as well as their author :)

[vlidholt]

Looking over the docs, there is definitely still work to do here:

• Private classes (not declared in the cocos2d.h) file are still visible in the documentation. Is there any way we can exclude these?
• Many descriptions have incorrect grammar, doesn't end with a period or doesn't start sentences with a capital letter.
• Some classes doesn't have a description that in any way explains what the do. E.g. CCAction, the complete description is Base class for CCAction objects. For newcomers this isn't very helpful.
• Some classes (physics are the ones that I've found) has @todo as their complete description.
• Some descriptions are misleading. E.g. CCSpriteFrame which states that you should use CCSpriteFrame *frame = [CCSpriteFrame frameWithTexture:texture rect:rect offset:offset]; [sprite setSpriteFrame:frame];, when the easier option and standard way is to use frameWithImageNamed:.

I think we still need someone to go through every single page and make sure they look good, are grammatically correct and is up-to-date.

[cocojoe]

Presume the commented out headers will be redundant (or base classes etc) at some point in the near future? So don't need to waste time tweaking documentation on them?

//#import "CCActionManager.h"
//#import "CCAnimation.h"
//#import "CCAnimationCache.h"
//#import "CCLabelAtlas.h"

//#import "CCParticleSystemBase.h"
//#import "CCParticleBatchNode.h"
//#import "CCTextureCache.h"
//#import "CCTextureAtlas.h"
//#import "CCScheduler.h"
//#import "ccFPSImages.h"

[cocojoe]

Found a bug in AppleDoc generator! This problem has been annoying me for a while, in the documentation there was a constant and page simply called ','. Turns out that if you use an enumeration with a type that is not just a single word it breaks. For example:

typedef NS_ENUM(unsigned char, CCPhysicsBodyType){

Have just changed to NSUInteger, can't see any issues with that? Can always typedef an unsigned char if need be.

[slembcke]

Oh! I forgot to push those changes from my other computer. I fixed that a few days ago. :-\ Apparently we made the same change though.

[Birkemose]

I noticed that a lot of properties in CCButton, are not documented?
I was trying to find out why zoomWithHighlight didn't work, but it is completely absent in docs.

[cocojoe]

OK an update to documentation status. Have worked through loads in my last pull request, about 1,700 changes heh.
I had to allow CCParticleSystemBase documentation otherwise it's not very helpful for learning CCParticleSystem.
Added basic sound header as no reason not to.
Have also added pragma marks where helpful in some multi interface headers.
Applied a bit of Obj-c best practice for a few headers as I've been going through them.

Still need to review:

CCActionCatmullRom
CCActionProgressTimer
CCActionProgressTime
CCDirector
cocos2d-ui/*
CCColor

@Birkemose Would you mind adding a little intro to CCScene about scene/nodes etc