YARDDocs.md

# Using YARD for Documentation

• Quick YARD cheat sheet
• YARD Getting Started Guide

You can run yard locally by running "yardoc" or "yard doc" (they do the same thing) from the repo, and "yard server" to run a local YARD docs server at "http://localhost:8808".

When to Use YARD vs Wiki

The Wiki is great for design notes, internal notes and things that are mostly interesting to the Scarpe team. Shoes3 API notes are interesting to Scarpe designers, but not really to casual users.

The YARD documentation is great for things that will be of interest to many or most users of Scarpe. The manual is great for Scarpe users and Scarpe team members, and it belongs in YARD in the Git repo.

The Wiki is great for quick collaboration and quick notes, where filing a PR would be a lot of work and there's not much need to carefully approve every change.

The YARD documentation is great for things that will be visible to end users, and where a review process ensures the results will be high-quality (but more work to write.)

There's clearly some gray area here, and we'll figure it out over time.

Example:

    # Creates a Shoes app with a new window. The block parameter is used to create
    # widgets and set up handlers. Arguments are passed to Shoes::App.new internally.
    #
    # @incompatibility In Shoes3, this method will return normally.
    #   In Scarpe, after the block is executed, the method will not return and Scarpe
    #   will retain control of execution until the window is closed and the app quits.
    #
    # @incompatibility In Shoes3 the parameters were a hash of options, not keyword arguments.
    #
    # @example Simple one-button app
    #   Scarpe.app(title: "Button!", width: 200, height: 200) do
    #     @p = para "Press it NOW!"
    #     button("clicky") { @p.replace("You pressed it! CELEBRATION!") }
    #   end
    #
    # @param title [String] The new app window title
    # @param width [Integer] The new app window width
    # @param height [Integer] The new app window height
    # @param resizable [Boolean] Whether the app window should be resizeable
    # @return [void]
    # @see Shoes::App#new