How to write documentation?

[groue]

Which format should we use to document our types and methods?

How can we render:

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

Maybe the jazzy README could sport sample Swift and Objective-C code, and a link to the generated documentation. That would be a nice introduction.

Today, I have difficulties having jazzy rendering a honest Swift documentation like the one below.

/**
The Template class provides Mustache rendering services.
*/
public class Template: MustacheBoxable {

    /**
    Parses a template string, and returns a template.

    Since templates usually compile fine, you don't have to explicitly perform
    any error handling:

    ::

      let template = Template(string: ...)!
      let rendering = template.render(...)!

    Eventual partial tags refer to resources with extension ``.mustache`` stored
    in the main bundle:

    ::

      // Uses `partial.mustache` resource from the main bundle
      let template = Template(string: "...{{>partial}}...")!

    :param: string The template string
    :param: error  If there is an error loading or parsing template and
                   partials, upon return contains an NSError object that
                   describes the problem.

    :returns: The created template
    */
    public convenience init?(string: String, error: NSErrorPointer = nil)

[segiddins]

Have a look at http://nshipster.com/swift-documentation/, it has a nice overview. Otherwise, please be more specific about how what jazzy renders differs from what you were expecting.

[groue]

Thanks @segiddins. I did look at mattt's article.

Let's be specific with, paragraphs, for example. Here is a simple example where jazzy does not render correctly paragraphs:

The doc (https://github.com/groue/GRMustache.swift/blob/faaa1b5e320452a017753108dc9d1221282d0c29/Mustache/Template/Template.swift#L240-L248):

    /**
    The template's base context: all rendering start from this context.

    Its default value comes from the configuration of the template
    repository this template comes from.

    :see: repository
    */
    public var baseContext: Context

Xcode shows two paragraphs:

Jazzy shows a single one:

[WCByrne]

Is there a reason that things like :see show up as small text rather than a section like the Apple documentation.

Also it would be great to add a quick example usage and maybe a list of supported markup. The NSHipster article only references :params and :returns. Not sure if any sort of code blocks, See Also, Note, or Discussion are supported. Not sure if I am doing something wrong or it just isn't supported yet.

[jpsim]

Is there a reason that things like :see show up as small text rather than a section like the Apple documentation.

That's a rendering issue with jazzy's CSS which we haven't gotten to fixing, though you're welcome to do so yourself. Help is always appreciated 😄.

[WCByrne]

Sounds good. If I get some time I'll play around with it. Thanks

[jpsim]

Closing as a duplicate of #77.