Documentation Guide
Introduction

See that edit link in the top right corner of the page? You can now, for better or worse, edit the documentation if you're a registered user.

You would think the documentation system would be good this time, but amazingly, it has evolved into an abomination again. This is because the whole system was nearly finished when people started demanding that it be made editable. The 'wiki' functionality is therefore haphazardly smashed on top of a system which was never intended for release, and it shows. Notably in the error reporting (or lack thereof).

Because the documentation consists of 'static' HTML pages, it must be regenerated manually after you edit a page.

Format

We needed a format less verbose than XML, and something suitable for web-editing. YAML is pretty close, but the whole indent-is-scope thing is a pain when it's not really needed. Existing wiki formats, like the one used by Wikipedia, are too general and article-centric.

The format we ended up with has no name (yet). It works like this:


 :key [data]

Where :key is the keyword (colon plus three letters), and data is any string that may be parsed in different ways depending on the keyword. Also, data can span multiple lines. In fact, data applies until the next :key or until the end of the file.

BBCode

Inline formatting, like bold, italic, underline and monospace.

There are two types of links. Global links, like Google, and LÖVE, and internal links, like love.graphics, love.graphics.setColor, FileMode, File and Introduction.

When referring to LÖVE, always write LÖVE without the umlaut. The umlaut will be added automatically.

Unordered lists.

  • One
  • Two

Ordered lists.

  1. One
  2. Two

Code without syntax highlighting and line numbers.


Some code goes here

Code without syntax highlighting, but with line numbers.

  1. Some code goes here.

Lua code in full glory.

  1. function foo()
  2.     return 1337;
  3. end

Guidelines
If we follow a few simple guidelines, everyone's lives will be much better.
  • Do use monospace when talking about variable names, function arguments and so forth. It makes it much easier to distinguish normal text with 'symbol names'. Example: If you add foo with bar, the result is always foobar.
  • Do use paragraphs in descriptions (:dsc) if looks better, but never on the first line (see first "don't").
  • Do add examples (:lua), but keep them reasonably short.
  • Do keep descriptions short. Create a :txt about something if there is much to say.
  • Do use the Lua type names if you're referring to a built-in type. Specifically, don't use float or int, use number in both cases.
  • Don't use BBcode in the first line of any description (:dsc). The first line is used as a short description in menus and so forth, and the BBCode will not be parsed there.
  • Don't use sections anywhere but in pages (:txt). Don't use it in descriptions for modules, types or functions. If there is much to say about something, create a :txt for the subject instead.
  • Don't document something you don't understand. No information is better than wrong information.
:mod
Creates a new module.

 :mod love

 :mod love.graphics

:typ
Creates a new type. You must use the "full" name of the type, so the type can be placed in the correct module. Still, no two types can have the same name, even if they are in different module.

 :typ love.graphics.Image

 :dsc A drawable Image object.

:fnc
Creates a new function.

 :fnc love.graphics.newImage

 :dsc Creates a new Image.

:dsc
Can be used to associate a description for modules, types, functions, constant groups, and pages (:txt).

 :mod love

 :dsc The root module.

:txt

Occasionally, you want to go in-depth on a certain topic. This keyword allows you to create 'custom' pages associated with a module, function, or type.

The first argument is the 'name' of the page, consisting of location ('love') and the filename ('page_license'). After that, an optional number indicates the priority of the page. Pages on the same parent will be ordered by their priority in descending order. Finally, a required title for the page (can contain spaces). This title is the identifier for the page. Therefore, no two pages can have the same title, even if they have different parents.


 :txt love.page_license 5 License

 :txt love.page_index 1000 Welcome

:arg

Creates an argument for a function.


 :fnc love.filesystem.exists

 :arg string filename The filename to check for existence.

 :ret bool exists True if file exists, false otherwise.

You can also specify a default value for an argument.

 :fnc love.filesystem.setColor

 :arg number r Red component (0-255).

 :arg number g Green component (0-255).

 :arg number b Blue component (0-255).

 :arg number a=255 Alpha component (0-255).

:ret

Creates a return value for a function. Functions may have multiple return values. Return values may not have defaults.


 :fnc love.filesystem.getColor

 :ret number r Red component (0-255).

 :ret number g Green component (0-255).

 :ret number b Blue component (0-255).

 :ret number a Alpha component (0-255).

:grp

Creates a new constant group on a module or type. No two groups can have the same name, even if they are in different modules.


 :grp love.filesystem.File.FileMode

 :con r Read mode.

 :con w Write mode.

 :con a Append mode.

:con

Adds a constant to the current :grp.


 :grp love.filesystem.File.FileMode

 :con r Read mode.

 :con w Write mode.

 :con a Append mode.

:lua
Adds an example to a module, type, or function.


 :fnc love.graphics.print

 :lua Hello World

 function love.draw()

     love.graphics.print("Hello World", 400, 300)

 end

:sup
Associates a type with a superclass. All functions from the superclass will appear in the subclass. Do not manually duplicate the functions of a superclass in the subclass; use this this keyword instead.


 :typ love.physics.CircleShape

 :sup love.physics.Shape

:see

Adds entries to the 'See Also' section of a function, module, or type.


 :fnc love.graphics.newImage

 :see love.image.ImageData

::::

You can use :::: for comments in the source.


 :::: This is a comment

Copyright © 2006-2010 LÖVE Development Team.