Better documentation :)

[stephencelis]

The README is very light on usage information and how jazzy parses documentation. Does it parse Markdown? reST? Which tokens does it support (in addition to :param:, :returns:)?

[juangamnik]

Perhaps the GitHub-Wiki can be used for this. One thing I do not know, e.g., is how to add my own frontage/readme in jazzy docs.

[jpsim]

jazzy looks for one of README.md, README.markdown, README.mdown or README (in that order) in the directory from where it run to render the index page at the root of the docs output directory.

See readme_generator.rb for more information.

This is certainly something we want to document when we start providing more comprehensive documentation for jazzy itself.

[AliSoftware]

On a side note, some flags of the CLI seems to lack documentation as well.
E.g. the --podspec flag does not have any description in the help banner 😉

[jessesquires]

@jpsim - It would be cool to be able to specify the path to the README.

The use case here:
I'm working on this framework, and I run jazzy from the framework/module directory, but my GitHub README is in the root directory.

[jpsim]

I definitely agree that jazzy needs much more usage documentation.

In the meantime, you can do the opposite for now: run jazzy from the root directory with the --source-directory DIRPATH option.

[groue]

Closed issue #162 had specific questions:

How can we render:

• paragraphs
• lists
• code blocks
• links to the internet
• links to other types and methods
• bold/italic text ?

[jpsim]

The answer is essentially Markdown. GitHub also has a good guide: https://help.github.com/articles/markdown-basics/.

Links to other code declarations aren't yet supported, but planned (see #13).

Function parameters and return values, however are defined via reStructuredText and look like this:

/**
    Lorem ipsum dolor sit amet.

    :param: bar Consectetur adipisicing elit.

    :returns: Sed do eiusmod tempor.
*/
func foo(bar: String) -> AnyObject { ... }

There's more to it than that, but this should be enough get you started. This issue is still open because I definitely agree, it would be good to document jazzy's behavior and capabilities in a more thorough and official setting.

[istx25]

What's the status on this? Can this issue be closed?

[jpsim]

No, there's a ton we could do to not just teach users how to use Jazzy, but how to even write standard Objective-C or Swift documentation comments.

Linking to Erica Sadun's blog post: http://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/

or her book: https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423?mt=11

or NSHipster's article: http://nshipster.com/swift-documentation/

maybe more.

[istx25]

Totally! Thanks for sharing these resources. I think we should also move some of the documentation out of the README.md and into the Wiki and go into more depth about certain topics.

[reitzig]

Fully agreed. Without looking into the setup of ReSwift, I'd not gotten anywhere. In particular, the custom categories feature is not even mentioned!