SketchApps Documentation

The SketchApps development environment uses mechanized documentation, in the form of "Court" (a YARD variant). YARD gathers information from both program source code and comments, then generates a set of web pages. Court merely tunes the process and output for SketchApps' needs.

Additional tools are under consideration; suggestions welcome...

Note: Court is only thought to run on Mac OS X! Please contact me if you would like to port it elsewhere...

YARD

YARD is Loren Segal's enhanced reimplementation of RDoc. I like the fact that it:

  • allows explicit markup for parameters, return values, etc.

  • parses the Ruby code, gathering much more information

  • separates the concerns of data collection and reporting,
    allowing variant formatters, post-processing of data, etc.

YARD markup format

YARD's markup format is a superset of the popular RubyDoc format (used by RDoc). Here are some useful resources:

Court

I'm a big fan of code folding in text editors. It lets me see content of current interest, hiding everything else. To aid in this, I put comment blocks inside the associated code section (eg, class, method), causing them to disappear along with the code. I'm also experimenting with semantic tags for comment blocks.

Court handles these markup variations, as well as some other issues. Specifically, the court script:

  • looks for a SketchApps_dev directory and subsidiary app trees

  • pre-processes each app tree, storing the output in .../Tmp/Court/doc

  • copies _Libraries/_Framework into each app's Tmp tree

  • runs YARD on each Tmp tree, including _Libraries/_Framework

  • Adds a "Court Index" page (SketchApps_use/court_index.html)

  • tweaks the YARD output (eg, adding links to the "Court Index" page)

Court markup format

Court's markup format is based on YARD conventions, with minor variations. The court script (a small wrapper for YARD) handles these variations, as well as handling file manipulation and some output tweaking.

Suggested structure

Court (ie, an interior yard) began as a way to allow comment blocks to exist inside the documented code sections (eg, module, class, method). This approach is not currently in vogue with the Ruby community, but it has several decades of precedent and works well with code folding in text editors (eg, TextMate).

The following code segment illustrates how you might set up a Ruby script to play nicely with Court. Note that:

  • Court-style documentation blocks have a rather precise location. They must immediately follow the section header line (eg, def) and have the same indentation level.

  • Conventional (eg, RDoc, YARD) placement of documentation block is also allowed, using traditional location rules.

  • A typical SketchApps distribution will have a motley collection of libraries, plugins, and scripts. To keep the namespaces distinct, all definitions should be enclosed in a class or module.

The following example script illustrates these points:

#!/usr/bin/env ruby
#
# awesome - Ruby script to do truly *awesome* stuff.
#
# @author Rich Morin

class Awesome
#
# This documents the +Awesome+ class.

  method main
  #
  # This documents the +main+ method.
  #
  # @return [void]
  ...
  end

  # This documents the +boring+ method.
  #
  # @return [void]

  method boring
  ...
  end

end

Awesome.new.main

Semantic tags

Preferably, ancillary comment blocks should use "=begin court-<type> ... =end" markup, eg:

  • court-coupling - class and instance variables, globals, etc.

  • court-legalese - copyrights, licenses, etc.

  • court-overview - architecture, caveats, usage, etc.

That said, court currently does nothing special with these blocks.

Usage

As noted above, Court is only thought to run on Mac OS X at present. It also requires the YARD gem, SketchApps version 0.3, and a SketchApps_dev directory tree.

Assuming that these preconditions are in place, you can run the court script and examine its output as follows:

% ~/Library/SketchUp/SketchApps_dev/_Lib*/_Fra*/Com*/Code/bin/court
% open ~/Library/SketchUp/SketchApps_use/court_index.html


This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r7 - 03 Jan 2012, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email