Did you ever wanted to work in a great team while giving back to developer community? Now’s your chance: I’m gathering a group of developers that would contribute to appledoc!

In the past 3 years, my client work has picked up and I hardly get some time to work on anything else. This includes both, my shareware and open source projects. One such a victim is also appledoc. It’s by far my most successful open source project, I definitely didn’t imagine it would pick up as much as it did when I started it back in 2008.

Anyway, back to present… Appledoc is currently used as documentation tool by almost every third party library vendor on Apple platforms. You can find many of those on cocoadocs. I’m really proud of this but also frustrated by my lack of time to work on it in any significant time chunks. Combined with some early design decisions, it makes it unnecessarily hard to avoid regressions or in some cases implement new features. Don’t get me wrong - appledoc is quite stable as it is, but there’s still areas where it can be improved and future proofed considerably. I get an opening here and there, but not enough to bring a project from start to finish, so I’m reaching out to developer community for help! I don’t expect anyone to jump in full time on it - I know how hard it is to get any time besides our jobs and families - but if each of us can devote a little bit of our time here and there, together we can make a difference! And that’s what the spirit of open source is all about - building and contributing back to community!

But there are also benefits to working on known open source projects - it’s good way to get your name and skills known to the world while doing something useful. Interesting for students or someone starting on platform for example. They can learn how to work in real-world multi-developer projects and make connections with other developers. Though, I prefer to see these as “side effects” rather than primary motivation :)

So, what are the changes I’m thinking about? There are two possibilities actually, one is to fix all loose ends of existing Objective-C project, the second is to start it from scratch in Swift and reuse parts that work well. I think the later would be far more appealing and fun for everyone involved, so here’s rough outline for core appledoc functionality:

• Parsing source files and generating intermediate structure. Current version uses custom parser, I’d like to move to clang. For start, Objective-C parsing would be enough, but once everything else works, Swift parsing should also be supported.
• Parsing source code comments. I think current solution is good approach, it would just need to be a little more robust. Basically it needs to preprocess source code and convert appledoc specific formatting (think of cross references, @param etc.) into standard Markdown which is then passed to a third party Discount library that would convert it to HTML.
• Generating HTML and DocSet using template files. I think current approach with GRMustache works well enough.

While above is rough top down overview, each step is composed of many details and can be divided to subtasks. So nobody takes more than they can chew on :) Unit tests are very important - the source code needs to be covered as much as possible. This is essential for preventing regressions while merging pull requests (I also plan to use Travis to help on this). All contributors will be added to appledoc project as well as private (so far) appledoc Slack channel which will be used as primary means of communication.

This brings me to my role: while I’ll certainly do some coding, my main task would be to manage the work between us and making sure we all row in the same direction.

But enough for now, if you’re interested, let me know through contact form, looking forward to hear from you!