Objective-c code Apple style documentation set generator.

Related tags

Tools appledoc
Overview

About appledoc

IMPORTANT NOTICE: collaborators needed

appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set. Although there are several tools that can create HTML documentation for Objective-C, all of those known to me fall short in meeting the minimum of goals described below.

Main goals of appledoc:

  • Human-readable source code comments.
  • Simple cross references to objects and members.
  • Generate Apple-like source code HTML documentation.
  • Generate and install fully indexed and browsable Xcode documentation set.
  • Single tool to drive generation from source code parsing to documentation set installation.
  • Easily customizable output.
  • 100% Objective-C implementation for easy debugging.

To make your experience with appledoc as smooth as possible, we warmly suggest reading this whole document as well as all online documentation mentioned in "using appledoc" section below!

Usage of appledoc is allowed under the terms listed in LICENSE section at the bottom of this file!

Want to keep updated? Follow us on Twitter - @gentlebytes.

Quick install

The recommended way is to clone GitHub project and compile the tool from Xcode. As cloning GitHub project will create the link to the main repository, it greatly simplifies future upgrading too. To install, type the following in the Terminal:

git clone git://github.com/tomaz/appledoc.git

This creates appledoc directory. Within you can find appledoc.xcworkspace Xcode workspace; open it and compile appledoc target - this should work out of the box, however your system must meet minimum system requirements, see below. I recommend you copy resulting appledoc executable from build directory to one of the directories in your path (echo $PATH) to make it easily accessible.

Optional: Appledoc is selfcontained and contains the necessary template files. IF you want to modify these default from Templates subdirectory to one of the expected locations:

  • ~/Library/Application Support/appledoc
  • ~/.appledoc

You can also use install-appledoc.sh script to perform quick installation. Open Terminal and switch to appledoc directory. Type following command:

sudo sh install-appledoc.sh (if you need templates add '-t default')

It compiles appledoc and installs its binary to /usr/local/bin and templates (if wanted) to ~/.appledoc by default. You can override this directories with -b and -t options respectively. For example:

sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

Alternatively with Homebrew:

brew install appledoc

Homebrew does not install templates by default.

Using appledoc

Use appledoc --help to see the list of all command line switches. Read more about appledoc on appledoc site. Also read wiki pages for some more in-depth articles.

Use appledoc Google group as a forum for questions on usage or other general questions.

Use appledoc issues page to submit bug and feature requests. Before submitting new issues, check the forums to see if your question is answered there - unless you can confirm your issue as a new feature request or a bug, you should start at the forum to keep GitHub issues clean. Also read through issues to see if the issue is already there and vote on it or add a comment (don't forget about closed issues).

Installation tips

To keep up to date, just go to Terminal and cd into appledoc directory, issue git pull and recompile appledoc.xcodeproj. Don't forget to overwrite appledoc executable you've copied to $PATH :)

If you also want to compile and run AppledocTests (unit tests) target, you need to copy all the frameworks indicated within Libraries & Frameworks group to shared frameworks directory before building unit tests target! This is not required for building the appledoc tool itself.

Integrating with Xcode

You can setup Xcode to automate appledoc document creation. Find out how using a Run Script and your project's Build Phases.

Docset usage tips

Pre-generated documentation and docsets for most Cocoa frameworks are available at:

Once you have a docset, you might want to use it with a documentation browser:

Troubleshooting

Have problems? This is what you can do to troubleshoot:

  1. Make sure you have the latest appledoc version. Try git pull and run with latest version again.
  2. IF you have template files installed, make sure you're using the latest - delete the predefined folders and have appledoc copy the files from its embedded archive again (see Quick Install section above).
  3. Increase verbosity level with --verbose command line switch. Default level is 2, but you can progressively increment verbosity up to 6 with each level giving you more detailed information. As this will give you a lot more information, you may want to concentrate only on specific set of source files you have problem with. Note that increasing verbosity will result in slower performance so using levels above 4 for every day use is not recommended.
  4. Appledoc is open source project! You have all the source code available, so run it from Xcode. You can setup Xcode to pass the desired command line arguments and add breakpoints to help you isolate your issue. If you feel you'd like to contribute more to community, you are welcome to fork the project on GitHub and add features to it. Keep us posted so we can add these features to main repository as well - include unit tests if possible.
  5. If you think you found a bug or want to request new feature, go to appledoc issues page. First read existing issues to see if there is already a request there (if you're using master branch, also read closed issues as your request may have already been covered but isn't yet merged on master branch). You can vote on existing requests to help us decide which features to concentrate on or you can add a comment to aid in solving it. If you don't find the request there, create a new issue; include parts of source files that give you problems if possible and/or description or steps that lead to it.
  6. If you're having problems with some of your source files and don't want to publish them online, you can contact us through email below. We'll do our best to help you out, but bear in mind appledoc is not commercial product; it's created and maintained in our spare time, so resources are limited.

Developer notes

If you wish to contribute, see the Developer Notes file for short overview of how appledoc works internally.

Minimum system requirements

  • Xcode 4.5 or greater for compiling
  • OS X 10.7 for compiling and running

License

appledoc is licensed with modified BSD license. In plain language: you're allowed to do whatever you wish with the code, modify, redistribute, embed in your products (free or commercial), but you must include copyright, terms of usage and disclaimer as stated in the license, the same way as any other BSD licensed code. You can of course use documentation generated by appledoc for your products (free or commercial), but you must attribute appledoc either in documentation itself or other appropriate place such as your website.

If for whatever reason you cannot agree to these terms, contact us through contact form on our about page, we'll do our best to help you out you out and find a workable solution!

Copyright (c) 2009-2011, Gentle Bytes All rights reserved.

Redistribution and use in source, binary forms and generated documentation, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Redistributions of documentation generated by appledoc must include attribution to appledoc, either in documentation itself or other appropriate media.

  • Neither the name of the appledoc, Gentle Bytes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Gentle Bytes [email protected]

Comments
  • Wrong Icons

    Wrong Icons

    File icons are used for classes (and everything produced by AppleDoc) in the "Browse" view of Organizer, yet when searching, they do come up with the class icon "C". Would be super great to have the browse show these also with the class icon. Thanks!

    opened by twobitunicorn 36
  • Xcode's QuickHelp not working with created DocSet

    Xcode's QuickHelp not working with created DocSet

    Xcode does not display QuickHelp for the DocSet I created with AppleDoc. The other parts of the Xcode integration work fine - I can see the project in the Help menu and the files are found when I right-click a keyword and choose "Find text in documentation".

    It does not seem to a problem with my setup - I asked other people to install my docset, and they reported the same results.

    Bug Known 
    opened by PrimaryFeather 25
  • Default DocSetPlatformFamily

    Default DocSetPlatformFamily

    Can you set the DocSetPlatformFamily key to default to "appledoc"? Having "appledoc" as the docset platform allows Dash (http://kapeli.com/dash) to recognise a docset as Appledoc-generated and enable extra features for it (table of contents and click-to-copy). Thanks!

    Feature 
    opened by Kapeli 23
  • OSX 10.8 Incompatibility

    OSX 10.8 Incompatibility

    Running appledoc on OSX 10.8 produces this crash:

    2012-03-08 18:31:51.507 appledoc[24139:707] -[__NSCFConstantString code]: unrecognized selector sent to instance 0x7fff76c3c590
    appledoc version: 2.0.4 (build 703)
    
    Oops, something went wrong...
    NSInvalidArgumentException: -[__NSCFConstantString code]: unrecognized selector sent to instance 0x7fff76c3c590
      @ 0   CoreFoundation                      0x00007fff8ceeaf06 __exceptionPreprocess + 198
      @ 1   libobjc.A.dylib                     0x00007fff8a71579a objc_exception_throw + 43
      @ 2   CoreFoundation                      0x00007fff8cf842aa -[NSObject(NSObject) doesNotRecognizeSelector:] + 186
      @ 3   CoreFoundation                      0x00007fff8ced956e ___forwarding___ + 414
      @ 4   CoreFoundation                      0x00007fff8ced9358 _CF_forwarding_prep_0 + 232
      @ 5   appledoc                            0x000000010c735e2b +[NSException(GBException) reasonWithError:message:] + 43
      @ 6   appledoc                            0x000000010c735dd0 +[NSException(GBException) raise:format:] + 480
      @ 7   Foundation                          0x00007fff89d15bd2 -[NSConcreteTask launchWithDictionary:] + 409
      @ 8   appledoc                            0x000000010c79c571 -[GBTask runCommand:arguments:block:] + 1617
      @ 9   appledoc                            0x000000010c798eba -[GBDocSetOutputGenerator indexDocSet:] + 426
      @ 10  appledoc                            0x000000010c796f7d -[GBDocSetOutputGenerator generateOutputWithStore:error:] + 541
      @ 11  appledoc                            0x000000010c775d03 __42-[GBGenerator runGeneratorStepsWithStore:]_block_invoke_0 + 803
      @ 12  CoreFoundation                      0x00007fff8cee3906 __NSArrayEnumerate + 582
      @ 13  appledoc                            0x000000010c775959 -[GBGenerator runGeneratorStepsWithStore:] + 713
      @ 14  appledoc                            0x000000010c77531e -[GBGenerator generateOutputFromStore:] + 414
      @ 15  appledoc                            0x000000010c72b963 -[GBAppledocApplication application:runWithArguments:] + 2419
      @ 16  appledoc                            0x000000010c7290d8 -[DDCliApplication runWithClass:] + 360
      @ 17  appledoc                            0x000000010c729427 DDCliAppRunWithClass + 103
      @ 18  appledoc                            0x000000010c728298 main + 56
      @ 19  appledoc                            0x000000010c728254 start + 52
    Command /bin/sh failed with exit code 250
    
    opened by odrobnik 22
  • Latest version doesn't install docset in XCode 5.0.1

    Latest version doesn't install docset in XCode 5.0.1

    I don't think the issue is Xcode, though.

    Symptom: Running Appledoc build does not result in docset being available in XCode's (still!) inferior docset viewer.

    Resolution: Reverting to commit aaca91b9b074d59718ea87e574fa4973022e2160 fixes the issue.

    opened by ExoticObjects 21
  • XCode does not show appledoc warnings

    XCode does not show appledoc warnings

    Hiyas

    If this has already been answered or asked before, I apologize, but a quick search for "xcode warnings" hasn't really dug up much. Anyways, I am sure this is a configuration problem on my own, but I can't figure it out how to make it correctly.

    What I want to do is to run appledoc and have it log everything it finds that isn't documented out so that XCode can pick it up when started using an Aggregate.

    I managed to make appledoc working and producing happily documentation with this run script in the aggregate:

    if [ -e "/usr/local/bin/appledoc" ]
    then
    /usr/local/bin/appledoc --create-html --install-docset --project-name "RMTXKit" --project-company "ABACUS Research AG" --company-id "ch.abacus" --output "/Users/misteli/dev/objc/iPhone/Libraries/RMTXKit/Documentation" --publish-docset –logformat=xcode --verbose xcode --keep-undocumented-objects --keep-undocumented-members --keep-intermediate-files --warn-undocumented-object --warn-undocumented-member --warn-empty-description --warn-unknown-directive --merge-categories --merge-category-comment --search-undocumented-doc --warn-missing-arg --no-repeat-first-par --no-warn-invalid-crossref --ignore "*.m" --ignore "*Test.h" --ignore "*Tests.h" --exit-threshold 2 --docset-package-url "http://www.abacus.ch/docs" --docset-feed-url "http://www.abacus.ch/docs" /Users/misteli/dev/objc/iPhone/Libraries/RMTXKit
    fi
    

    I experimented around using the $(PROJECTNAME) variables and more, but for the sake of being able to quickly run it in the console, this current version doesn't use that.

    So.. this builds up all my documentation but it doesn't log anything that isn't documented. Also, if I simply copy/paste the call to a console, appledoc happily runs, creates the documentation but whilst its running it doesn't log anything out other than its version and build number.

    What did I forget to add?

    Thanks!

    Bug 
    opened by fuggly 20
  • Documentation created with appledoc no longer shows quickhelp option to view in Xcode's organizer (4.4)

    Documentation created with appledoc no longer shows quickhelp option to view in Xcode's organizer (4.4)

    When a method is opt+click'd, there is a quickhelp bubble. There used to be an option in this bubble to read more in the organizer, but this option is no longer available for appledoc-generated documentation, starting with Xcode 4.4.

    Known 
    opened by ryanrhee 17
  • Exit value not zero if successful

    Exit value not zero if successful

    The Exit value for the new build appears to be 245 if successful or 1 if not rather than zero and the values posted in the changelog, excerpt from calling shell script in Xcode build below:

    !/bin/sh

    MakeDocumentation.sh

    iHF iPhone Library

    Created by David Jehring on 28/04/2011.

    Copyright 2011 Black Pear Software Ltd. All rights reserved.

    KEEP_FILES command line paramenter only populated if local html directory exists

    if [ -d "${HOME}/Development/Devhelp" ]; then KEEP_FILES="--keep-intermediate-files" else KEEP_FILES="" fi

    PUBLISHDIR=${HOME}/Development/Devhelp/bpiHF

    /usr/local/bin/appledoc
    --project-name "Black Pear iHF"
    -o "${SOURCE_ROOT}/help"
    --docset-bundle-name "Black Pear iHF"
    --merge-categories
    --verbose 3
    --docset-feed-url http://blackpear.com/devhelp/%DOCSETATOMFILENAME
    --docset-package-url http://blackpear.com/devhelp/%DOCSETPACKAGEFILENAME
    --publish-docset
    "${KEEP_FILES}"
    --print-settings
    "${SOURCE_ROOT}/iHF/Interface/iHRDataInterface.h"
    "${SOURCE_ROOT}/iHF/Plugin Support/iHFPrescribingDelegate.h"
    "${SOURCE_ROOT}/iHF/Plugin Support/iHFPrescribingProtocol.h"
    "${SOURCE_ROOT}/iHF/Plugin Support/iHFCodeBrowsingDelegate.h"
    "${SOURCE_ROOT}/iHF/Plugin Support/iHFCodeBrowsingProtocol.h"
    "${SOURCE_ROOT}/iHF/Plugin Support/iHFCodedItemExt.h"
    "${SOURCE_ROOT}/iHF/Categories/iHRPersistableObjectExt.h"

    RET=$? if [ $RET -ne 245 ];then echo "Apple doc failed with $RET" exit $RET fi

    Bug 
    opened by djehring 16
  • Possibility to add arbitrary documentation such as main page

    Possibility to add arbitrary documentation such as main page

    This would not be attached to any class, category or protocol. It should prefferably be completely decoupled from source files - as a set of "external" files created outside picked up by appledoc and copied to output directory.

    Ideally, this should be somewhat processed by appledoc for cross references and use the same markdown syntax.

    Additionally, there should be a way to link to this static documentation from within standard source code comments. It would also be nice to have it linked as companion guide so that it would also get listed in doc set.

    Feature 
    opened by tomaz 16
  • Install fail

    Install fail

    Xcode 7.2 OS: El Capitan 10.11.3

    I follow readme to start documentation, but on sudo sh install-appledoc.sh a got a install failed.

    ld: library not found for -lDiscount
    clang: error: linker command failed with exit code 1 (use -v to see invocation)
    
    ** INSTALL FAILED **
    
    
    The following build commands failed:
        Ld /tmp/appledoc.dst/usr/local/bin/appledoc normal x86_64
    (1 failure)
    

    Obviously i install pod and project build correctly on xcode but not with sh, so i dont get the binary exported It's a bug or i miss something ?

    opened by KevinJue 15
  • Put appledoc documentation on GitHub

    Put appledoc documentation on GitHub

    I am new to appledoc, and I understand the documentation for appledoc was not migrated when you moved to a newer site.

    It's a bit difficult without documentation, and a documentation tool with no documentation is a bit ironic ;)

    I know GitHub has a wiki feature. How hard would it be to as least copy paste the old doc here and take it from there slowly?

    opened by NathanHazout 15
  • brew install appledoc not working

    brew install appledoc not working

    Warning: No available formula with the name "appledoc". Did you mean apidoc?
    ==> Searching for similarly named formulae...
    This similarly named formula was found:
    apidoc
    To install it, run:
      brew install apidoc
    ==> Searching for a previously deleted formula (in the last month)...
    Error: No previously deleted formula found.
    ==> Searching taps on GitHub...
    Error: No formulae found in taps.
    
    opened by arnavdani 0
  • AppleDoc DON't support @textblock or @code

    AppleDoc DON't support @textblock or @code

    Hi, rencently I used AppleDoc to generate API doc for Objective-C SDK. It is amazing. But I found it seems to not support @textblock and @code tag. I know appleDoc support to write code block with a tab or 4 (or more) spaces.. But I want to use @textblock or @code because which can show example code in quick help of XCode, as shown below. How can AppleDoc parse @textblock or @code tag? image

    opened by afatcoder 1
  • The method declaration line break

    The method declaration line break

    Hi, AppleDoc, Current, the doc generated by appledoc show the method declaration as below image

    But I hope it has line break after every paramet, like apple official doc. How can I do? image

    opened by ErazerControl 1
  • Applying XCTest

    Applying XCTest

    Development Environment

    • Xcode 11.3.1 (11C504)
    • macOS Catalina 10.15.4 Beta (19E234g)

    Deployment Target

    • macOS 10.7

    Change Log

    • GHUnit is removed because it's a deprecated project.
    • XCTest is applied.
    • Code coverage is enabled.
    • GBLogX... is replaced with GBLog.... GBLogX... is supposed to print the file name that has the log. But DDLog that GBLog... and GBLogX... are using has an issue to print character array. In order to set the file name to nil, some macros are copied into GBLog.h from DDLog. This is a workaround.

    Todo

    opened by jebeomgyeong 6
Releases(2.2.1)
Xcode .appiconset generator for Adobe Illustrator.

Creating AppIcon sets from Adobe Illustrator This repo is rewrited from original repo https://github.com/CaryChamplin/CreatingIconsFromAI. Just genera

gitmerge 73 Nov 9, 2020
AVXCAssets Generator takes path for your assets images and creates appiconset and imageset for you in just one click

AVXCAssets Generator Often while developing an app, We ran into a condition when we need to scale images to each and every aspect ratios for icons and

Angel Vasa 336 Aug 16, 2022
Soulful docs for Swift & Objective-C

jazzy is a command-line utility that generates documentation for Swift or Objective-C About Both Swift and Objective-C projects are supported. Instead

Realm 7.2k Sep 15, 2022
An Xcode Plugin to convert Objective-C to Swift

XCSwiftr Convert Objective-C code into Swift from within Xcode. This plugin uses the Java applet of objc2swift to do the conversion. Noticed that the

Ignacio Romero Zurbuchen 338 Sep 7, 2022
An Xcode plug-in to format your code using SwiftLint.

SwiftLintXcode An Xcode plug-in to format your code using SwiftLint. Runs swiftlint autocorrect --path CURRENT_FILE before *.swift file is saved. IMPO

Yuya Tanaka 348 Sep 18, 2022
SwiftGen is a tool to automatically generate Swift code for resources of your projects

SwiftGen SwiftGen is a tool to automatically generate Swift code for resources of your projects (like images, localised strings, etc), to make them ty

null 8.2k Sep 23, 2022
Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer documentation.

Swift-DocC is a documentation compiler for Swift frameworks and packages aimed at making it easy to write and publish great developer docum

Apple 791 Sep 20, 2022
docc2html - A static site generator for DocC documentation archives

Tool to convert "DocC" archives, a format to document Swift frameworks and packages: Documenting a Swift Framework or Package, to a static HTML site.

DocZ 103 Sep 2, 2022
A documentation generator for Swift projects

swift-doc A package for generating documentation for Swift projects. Given a directory of Swift files, swift-doc generates HTML or CommonMark (Markdow

SwiftDoc 1.7k Sep 23, 2022
Style Art library process images using COREML with a set of pre trained machine learning models and convert them to Art style.

StyleArt Style Art is a library that process images using COREML with a set of pre trained machine learning models and convert them to Art style. Prev

iLeaf Solutions Pvt. Ltd. 220 Jun 30, 2022
JSPatch bridge Objective-C and Javascript using the Objective-C runtime. You can call any Objective-C class and method in JavaScript by just including a small engine. JSPatch is generally used to hotfix iOS App.

JSPatch 中文介绍 | 文档 | JSPatch平台 请大家不要自行接入 JSPatch,统一接入 JSPatch 平台,让热修复在一个安全和可控的环境下使用。原因详见 这里 JSPatch bridges Objective-C and JavaScript using the Object

bang 11.3k Sep 21, 2022
Generate Markdown documentation from source code

SourceDocs SourceDocs is a command line tool that generates markdown documentation files from inline source code comments. Similar to Sphinx or Jazzy,

Eneko Alonso 344 Sep 14, 2022
Generate Markdown documentation from source code

SourceDocs SourceDocs is a command line tool that generates markdown documentation files from inline source code comments. Similar to Sphinx or Jazzy,

Eneko Alonso 344 Sep 14, 2022
Code and documentation for my talk Anime-fy Yourself Using Core ML

Anime-fy Yourself Code and documentation for my talk Anime-fy Yourself Using Core ML Convert from PyTorch to Core ML To convert @bryandlee's PyTorch i

Yono Mittlefehldt 2 May 29, 2022
A beautiful set of predefined colors and a set of color methods to make your iOS/OSX development life easier.

Installation Drag the included Colours.h and Colours.m files into your project. They are located in the top-level directory. You can see a demo of how

Ben Gordon 3.1k Sep 12, 2022
This framework implements a strict JSON parser and generator in Objective-C.

SBJson 5 Chunk-based JSON parsing and generation in Objective-C. Overview SBJson's number one feature is stream/chunk-based operation. Feed the parser

null 3.8k Sep 9, 2022
Swift-friendly API for a set of powerful Objective C runtime functions.

ObjectiveKit ObjectiveKit provides a Swift friendly API for a set of powerful Objective C runtime functions. Usage To use ObjectiveKit: Import Objecti

Roy Marmelstein 852 Sep 14, 2022
Swift ports of Apple's Objective-C / C++ sample code

MetalSampleCodeSwift Swift ports of Apple's Objective-C / C++ sample code Metal is a great API, but it can feel inaccessible for Swift developers due

Jonathan Hobson 2 Jul 20, 2022
nef💊a toolset to ease the creation of documentation in the form of Xcode Playgrounds

nef, short for Nefertiti, mother of Ankhesenamun, is a toolset to ease the creation of documentation in the form of Xcode Playgrounds. It provides com

Bow 253 Sep 7, 2022
The iOS framework that grows only as fast as its documentation

Nimbus is an iOS framework whose feature set grows only as fast as its documentation. Support status Nimbus is in a supported maintenance mode, meanin

featherless 6.5k Sep 9, 2022