search

C4Labs / C4iOS

C4 is an open-source creative coding framework that harnesses the power of native iOS programming with a simplified API that gets you working with media right away. Build artworks, design interfaces and explore new possibilities working with media and interaction.
www.c4ios.com
MIT License
979 stars 75 forks source link

Documentation #173

Closed traviskirton closed 10 years ago

traviskirton commented 10 years ago

We need to evaluate the use of AppleDocs for docset management. Currently, the docs are built directly from the header files in the C4 project, but I'm not sure if that will work any more. The process for generating documentation needs to be modernized and integrated with how we build the new framework / lib / etc., so that the two go hand in hand.

We should also consider feedback such as:

alejandro-isaza commented 10 years ago

I think the documentation has to be in the source code. Maintaining a parallel documentation document is a nightmare and in the best case it is always going to be one step behind the code. We can have an automated system that extracts the documentation from the code into a page. See http://cocoadocs.org we get that for free with CocoaPods.

traviskirton commented 10 years ago

I was using AppleDoc, http://gentlebytes.com/appledoc/ , which does a great job for generating Apple style documentation. It has grown a lot since I started using v0.9, so there's probably some wicked improvements. Like many open-source projects, documentation is a bit raw on how to use it. However, it seems to still be quite active with 64 contributors, and the latest merge on Oct 5.

It was a two-step process. Add documentation to the headers, run AppleDoc on the framework. This actually produces a docset identical to the ones you can search via Xcode, and it was easily installable from the pkg, which was really handy. Also, the added feature of the ctrl-click search in Xcode was nice.

traviskirton commented 10 years ago

Wham. From the cocoadocs readme page ( http://cocoadocs.org/readme/ ):

"...you will need a working copy of appledoc..."

if cocoadocs uses the same markdown as appledoc, then i think that's two birds w/ one stone...

alejandro-isaza commented 10 years ago

Yeah, having Xcode show you the documentation in-line is really useful. The only problem is that appledoc doesn't seem to support Swift yet. Also Xcode doesn't format Swift comments as nicely as ObjC. But I'm sure this will be fixed soon.

traviskirton commented 10 years ago

Idea Maybe there could be a "doc viewer" app? A desktop thing that would allow people to search, view, copy / paste code, download playgrounds, etc.