How to generate HTML documentation for SWIFT files in Xcode with HeaderDoc?

Question

I tried to document my Swift project in Xcode with HeaderDoc, but are processed only files ".h" and are ignored files ".swift"

This is my swift File:

/// test
///
/// :param: ann blabla
func testFunc( ann: Foo ) { .. }

I run the following in the Terminal:

headerdoc2html -o ~/Desktop/docum Ninja

This is the error:

    Documentation will be written to /Users/me/Desktop/docum
    HTML output mode.
    No valid input files specified. 

        Usage: headerdoc2html [-dq] [-o <output directory>] <input file(s) or directory>.

    iMac:MyApp me$  headerdoc2html -o ~/Desktop/docum Ninja/

    Documentation will be written to /Users/me/Desktop/docum
    HTML output mode.
    DIR Ninja/
    ======= Parsing Input Files =======

    Processing Ninja/Test.m
        Skipping. No HeaderDoc comments found.

    Processing Ninja/-Bridging-Header.h

Hindustan

Answer 1

Yeah...

As of right now, HeaderDoc cannot convert Swift inline-documentation into HTML files using headerdoc2html. You, and everyone (myself included) will sadly have to wait.

---

Other options

So the 'big three' iOS code documentation tools are HeaderDoc, AppleDoc, and Doxygen. Sadly, all three do not support Swift. Good news: AppleDoc is coming out with v3.0 relatively soon and the other two may (probably will) also update as well. AppleDoc is open source, so if you are code savvy, you could adapt it to fit your needs (with swift and all that jazz)

EDIT:

I commented on AppleDoc's Github page and got a couple replies. Mainly, on October 16, 2014 apple is having a conference. After this conference, the AppleDoc guys (gals?) will begin adding Swift support to AppleDoc 3.0 and it will be released at some point.

---

Speaking of Jazz

Jazzy is something out right now (!) and can generate documentation in the form of HTML for Swift (!!) I had a hard time setting it up, and it's format is unorthodox, but if you can't wait for the big three to update, it may just be for you.

good luck with your adventure.

ZR

Irmgardirmina

Awesome, thanks so much! jazzy works great for me. @MohitAthwani - This comment might help you if you are using an xcworkspace: github.com/realm/jazzy/issues/111#issuecomment-67039330 – Orison

@nathan.f77 I love you for pointing me to that link ... Jazzy works like a charm ! I wonder how you managed to guess that I was using a workspace ... – Leach

"v3.0 relatively soon" - what exactly made you say that? It's almost 4 months since your post and there's no indication that v3 is going to be public (or usable) anytime soon. – Hellenhellene

@LearnCocos2D 4 Months ago I asked the lead developer on Github when v3.0 would be released. He said that it would be released shortly; it hasn't been released. Thus his definition of short is either half a year, or he miscalculated. – Irmgardirmina

Also loving Jazzy at the moment. – Phagy

jazzy not work with pods project, Can you guide me there how to do the t – Cusick

Answer 2

For documenting Swift frameworks, libraries, & packages, Apple introduced DocC at WWDC 2021 to generate documentation in Xcode and to host on the web. It does not however, generate HTML.It generates a package that can then be exported and hosted on your website. See this video for the basics of generating documentation using DocC. I also found a good article here that helped me get started. This is an Xcode 13 feature, so it is still in Beta as of this writing. For how to host this documentation from the generated .doccarchive package in Xcode, Apple has a video explaining how to do that here although I have heard of people running into some issues with that tool.

Taam