Here is an example of how to document a Live Code Handler. See LiveCode Documentation Format Reference for further information.
Below are the tags that are supported by the handler documentation in Livecode: * Name: * Type: * Syntax: * Introduced: * OS: * Platforms: * Security: * Example: * Parameters: * number: * callbackMessage: * Description: * References: * Tags:
You will also be able to document LiveCode script using exactly the same syntax, and autogenerate an API for it, if for example you are writing a library for distribution. The idea would be that you could add tabs in your dictionary viewer for each of the stacks that is currently being used as a library, as a handy reference tool.
Below are a couple of examples of a fully documented handler. Here is an example of what a handler will look like when documented and displayed in Fedwiki:
Sets the specified metadata item for pObject to pValue
The first example is for documentation in a separate file:
Name: textEncode Type: function Syntax: textEncode(<stringToEncode>, <encoding>) Summary: Converts from text to binary data. Introduced: 7.0 OS: mac,windows,linux,ios,android Platforms: desktop,server,web,mobile Example: textEncode("A","UTF16") Example: put textEncode(field "output","UTF-8") into tOutput put tOutput into url ("file:output.txt") Parameters: stringToEncode (string): Any string, or expression that evaluates to a string. encoding (enum): the encoding to be used - "ASCII" - "ISO-8859-1": Linux only - "MacRoman": OS X only - "Native": ISO-8859-1 on Minux, MacRoman on OS X, CP1252 on Windows - "UTF-16" - "UTF-16BE" - "UTF-16LE" - "UTF-32" - "UTF-32BE" - "UTF-32LE" - "UTF-8" - "CP1252" Returns: Returns the <stringToEncode> as binary data. Description: Converts from text to binary data. The <textEncode> function takes text, and returns it as binary data, encoded with the specified encoding. It is highly recommended that any time you interface with things outside LiveCode (files, network sockets, processes, etc) that you explicitly textEncode any text you send outside LiveCode and <textDecode> all text received into LiveCode. If this doesn't happen, a platform-dependent encoding will be used (which normally does not support Unicode text). It is not, in general, possible to reliably auto-detect text encodings so please check the documentation for the programme you are communicating with to find out what it expects. If in doubt, try UTF-8. References: textDecode (function)
The next example is for inline markup in the Script Editor:
/* Summary: Extracts the inline docs from a .lcb file pFile: The path to the .lcb file to extract docs from Returns (string): A string consisting of all the docs for the library, and the syntax and handlers present in the .lcb file Description: <revDocsGenerateDocsFileFromModularFile> is used when packaging a widget to create its API documentation. It generates the Library and Type elements from the declaration in the <pFile> (either widget or library), and extracts the comment block that precedes any initial declaration for use as the library-level Description element. It then extracts the comment blocks that precede syntax and handler definitions in <pFile>, and generates the Name, Type, Syntax, and Associated elements for each entry, as well as the parameter types. Tags: Package building */ function revDocsGenerateDocsFileFromModularFile pFile ... end revDocsGenerateDocsFileFromModularFile
Name: accept Type: command Syntax: accept [datagram] connections on port <number> with message <callbackMessage> Summary: Accepts an internet connection and creates a <socket> for that connection. Introduced: 1.0 OS: mac,windows,linux Platforms: desktop,server,web Security: network Example: accept connections on port 80 with message "connectionMade" Example: accept datagram connections on port 80 with message "connectionMade" Example: on mouseUp accept connections on port 80 with message "connectionMade" end mouseUp on connectionMade pIPAddress put "Connection made:" && pIPAddress end connectionMade Parameters: number: callbackMessage: The name of a message to be sent when a connection is made or a datagram is received. portNumber: The TCP port number on which to accept connections. Description: Use the <accept> <command> when running a <server>, to accept <TCP> connections or <UDP> <datagram|datagrams> from other systems (or other <process|processes> on the same system). Use the datagram option if you want to accept UDP datagrams. When a connection is made or a datagram is received, the <accept> <command> creates a new <socket> that can be used to communicate with the other system (or <process>). When using the <close socket>, <read from socket>, or <write to socket> <command|commands>, you can refer to this <socket> with a socket identifier that looks like this: host:port[|connectionID] where the connectionID is a number assigned by the <accept> <command>. (You only need to specify the connection number if there is more than one <socket> connected to a particular <port> and <host>.) The <callbackMessage> is sent to the <object> whose <script> contains the <accept> <command>. Either one or two <parameter|parameters> are sent with this <message>. The first <parameter> is the <IP address> of the system or <process> making the connection. If a <datagram> is being accepted, the second <parameter> is the contents of the <datagram>. For technical information about sockets, see RFC 147 at http://www.ietf.org/rfc/rfc147.txt. For technical information about UDP datagrams, see RFC 768 at http://www.ietf.org/rfc/rfc0768.txt. For technical information about the numbers used to designate standard ports, see the list of port numbers at http://www.iana.org/assignments/port-numbers, in particular the section entitled "Well Known Port Numbers". References: HTTPProxy (property), script (property), read from socket (command), write to socket (command), close socket (command), open socket (command), openSockets (function), hostAddressToName (function), hostName (function), hostAddress (function), peerAddress (function), hostNameToAddress (function), datagram (glossary), IP address (glossary), TCP (glossary), port (glossary), command (glossary), socket (glossary), UDP (glossary), host (glossary), server (glossary), message (glossary), parameter (glossary), process (glossary), object (object) Tags: networking