Skip to content
This repository has been archived by the owner on Jan 3, 2019. It is now read-only.

API Documentation

Jump to bottom
wpbasti edited this page Oct 5, 2012 · 19 revisions

Generating API docs in Jasy is a cooperation of three projects:

  • Jasy: Parsing and processing JavaScript code + exporting data
  • Core: Basic JavaScript library used in conjunction with Jasy projects
  • API Browser: Web application for navigating and rendering the Jasy generated data

Philosophy

Don't repeat yourself

At developing the API data generator in Jasy we did not like the approach done by other tools to add tons of comments to the code just to fulfill the needs of the documentation system (e.g. telling a method that it's a member of a class). We preferred adding intrinsic support for specific class and module declarations instead and make supporting them automatically our priority.

Less but better comments

We felt that JSDoc repeat a lot of text. This gets especially annoying with short methods and trivial function signatures and documentation tasks. One has to typically write a lot of stuff here as well, just to correctly document things.

Markdown for the win

The API system uses Markdown for everything text. Markdown makes writing readable text easy and could be easily transformed into HTML. It supports injecting code blocks via indenting or via so-called fenced blocks.

Integrated syntax highlighter

All code blocks are automatically highlighted. Language to highlight can be specified in fenced code blocks (e.g. support for PHP, Python, etc. is included). The default highlighting is JavaScript.

Features

  • Syntax Types
    • All Core features including multiple inheritance, mixins, interfaces, events and properties
      • Copying documentation from interfaces
      • Inlining members, events, properties from mixins while highlighting their origin
      • Mark overridden items
    • Plain JavaScript object assignment
    • Plain JavaScript prototype based classes
  • Linking
    • Generating API data across all included projects
    • Cross project inheritance/include/override
    • Linking to methods, properties, events
  • Tagging
    • Marking all documented items via tags for simple categorization features e.g. #deprecated
    • Parametrized tags e.g. #since(1.0).
  • Highlighting:
    • Full JavaScript source code
    • Code section in documentation comments
  • Package Docs:
    • Package level documentation (placing an index.md or readme.md inside any class folder).
    • Auto listing and summarizing classes of a package in package overview page.
  • Markdown
    • Convert all documentation comments via Markdown for easy and writable and human readable documentation comments.
    • Convert package docs using Markdown as well.
    • Generate plain summary texts for all comments based on the first sentence to show in compact/list views.
  • Parameters
    • Full range of parameter handling with support for marking as optional, with default values
    • Support for variable arguments lists e.g. function sum(varargs) { return ... }
  • Exporting
    • Generated separate files for dynamic loading of class data
    • Meta data index for building a tree/list of all classes
  • Error Handling
    • Detect and collect documentation errors during generating API data
    • Verify links between classes or to members/events/properties
  • Search: Generating word index for client side search logic
  • Basic variable resolving logic when using assignments in class declaration
  • Private/Internal: Mark private/internal methods and hide them by default
  • Caching: Cache API data for all unmodified JavaScript files
  • Size Analysis: Show statistics on optimized / compressed size of each class.
  • Dependency Analysis: Show which dependencies a class has to better understand the effects of including it.

Task

Generating the API data and the API browser is pretty easy by simply adding a new task to your jasyscript.py and fulfilling the requirements of the projects required.

Add this task to your jasyscript.py:

@task
def api():
    """Build API viewer"""

    Task.runTask("apibrowser", "build")
    ApiWriter(session).write("$prefix/data")

Be sure to have Core and API Browser in your project requirements (jasyproject.yaml/json) e.g.:

requires:
- source: https://github.com/zynga/core.git
  version: 0.8
- source: https://github.com/zynga/apibrowser.git
  version: 0.6

Then generating the API Browser for your project (and all required projects included) is as simple as:

$ jasy api

This generates a new top level folder called "api" with:

  • The compiled API Browser
  • Jasy generated API data for your projects
  • Highlighted JavaScript files

The folder is self-contained an can be moved/copied anywhere easily.

Formats

Supported Constructs

Currently Jasy handles code written using the Core library or plain simple JavaScript constructs (with no additional magic applied):

  • Core Library:
    • core.Module
    • core.Class
    • core.Interface
    • core.Main.declareNamespace
    • core.Main.addStatics
    • core.Main.addMembers
  • Vanilla JavaScript:
    • some.name.Space = {}
    • some.name.Space = function() {} (together with prototype for members)

Future Extendable

The approach in general is designed to be extendable so more styles might be supported in future versions. Jasy generally supports these lists for each class/file:

  • Module
    • Statics
  • Class
    • Constructor
    • Members
    • Properties
    • Events
    • Includes
    • Implements

New styles which should be added must also conform to these two groups for making further analysis possible.

Documenting

Code comments are formatted using normal JSDoc like comment styles. Both formats, the compact and verbose, produce the same results. Verbose allows for multiline code blocks, lists, headers and other Markdown features.

Compact Formatting

/** Calculates the result */
function calc() {}

/** {Number} Returns the result */
function calc() { return this.x1 + this.x2; }

/** {Number} Calculates and returns the sum of @x and @y */
function sum(x, y) { return x+y; }

Verbose Formatting

/** 
 * Calculates the result 
 */
function calc() {}

/** 
 * {Number} Returns the result 
 */
function calc() { return this.x1 + this.x2; }

/** 
 * {Number} Calculates and returns the sum of @x and @y 
 */
function sum(x, y) { return x+y; }

Parameters

Parameters have to use the @ in front of the name of the parameter. The type of the parameter or its default values only needs to be assigned once to the parameter. These data is defined using curly brackets {Number} after the name of the parameter.

/** 
 * {Number} Calculates and returns the sum of @x {Number} and @y {Number}
 */
function sum(x, y) { return x+y; }

Defining these hints directly inside the written sentence makes comments a lot more compact and far easier to read. And it also omits duplicating the work of creating and maintaining these information.

Return Types

If you wondered about the leading {Number}. That's the return type of the method sum. By convention if the first thing in a comment is a block of curly brackets it is parsed as a return value (or static type).

Static Types

These are used on non-functions to define the type for static members. Most of these types are figured out automatically. Static type hints are used to fill in the gaps or to correct misunderstandings by the auto detection in Jasy. Static types are defined just like return types, but the first character in the open brackets needs to be a equal sign.

core.Module("my.Module", 
{
  /** {=Date} Start time */
  start : new Date()
});

Links

Tags

Clone this wiki locally