Documenting the Library

Documenting the library

Extensions can provide an API (Dictionary) and User Guide as part of the installed package. They are installed and viewable through the LiveCode Dictionary stack.

Any extension can include an API. To do so, either add a file called ‘api.lcdoc’ to your widget folder alongside the other widget files or markup your source code inline. The ‘api.lcdoc’ file must be in the lcdoc format. For a full description of the lcdoc format see the Contributing to LiveCode Documentation guide.

Marking up your code

In this example we will document the library using inline code comments.

Marking up your scripts is simple and follows a similar model to other documentation formats.

Consider the following handler:

public handler myHandler(in pString as String, in pNumber as Number)
 -- Code 
end handler

To add an entry to the API for this handler, place a formatted comment above the handler definition:

/**
summary: Use this handler to do an action
pString: This parameter does x
pNumber: This parameter does y
description:
# Markdown Title
Here is a full description in markdown for how this function works. Once again, any GitHub flavoured markdown is accepted.
**/
public handler myHandler(in pString as String, in pNumber as Number)
 -- Code 
end handler

Documenting sayHello

We want to markup the source code of the Hello World library by adding inline documentation to the sayHello handler.

• The documentation is enclosed within /** and **/
• Add a summary.
• Add a description of the pNames parameter.
• Add a description of the return value.
• Add a full description of how the handler works.

/**
Summary: Constructs and retuns a list of Hello messages
pNames: String containing a comma separated list of names
Returns: List of Hello strings 
Description:
Takes a comma separated String of names, converts the String to a List, constructs a Hello message for each name and returns the List of Hello messages.
**/
public handler sayHello(in pNames as String) returns List
 ... handler code
end handler