Skip to content

YARDDocs.md

Jump to bottom
Noah Gibbs edited this page Oct 10, 2023 · 5 revisions

Using YARD for Documentation

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".

YARD and Extensibility

One reason YARD is good at documenting Ruby is that it's very extensible. If you have a method you can call that will create other methods or attributes, YARD may well have a way to express that. It can't pick up everything automatically, but you can give it hints. The way to do this is with what YARD calls "directives" or "behavioral tags".

It's also possible to extend YARD's output format for more context- and output-specific effects, but that's more involved and, as a rule, more difficult.

YARD Types

YARD encourages labelling params, return values, blocks, etc with the types they accept and return. But also, this is Ruby. YARD has a spec for types, and it an be a bit freeform. It is not the same as Sorbet or RBI -- YARD uses an older syntax.

But here's an interactive type parser for YARD, along with various examples:

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
    # drawables 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
Clone this wiki locally