API Documentation with AppleDoc about cocos2d-objc

[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 [email protected] 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 [email protected]:

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