Area 51/Template

This template should be followed when creating new entries in documentation.

Its source code can be copied and pasted and used as a framework for a new entry.

It is heavily commented. Each comments line starts with "--" (as Lua comments that won't work on a Wiki page!)

Remember to generally strip out each comment line before publishing a new documentation!

You are encouraged to use the Area_51 documentation page to prepare documentation for not-yet-published functionality.

<< Back to Area_51

Contents of a documentation entry

In the past, we did not always honor the same order. It is important to unify so reader's expectations are met and important information is found quickly.

The following example uses this order of information:

1. headline
2. function signature
3. description
4. see also
5. mudlet version
6. note
7. parameters
8. returns
9. example
10. additional notes for developers, etc.

functionName

The headline will be the function name. That is the only part of the headline that will be transferred to main documentation. However during Area 51 stay, please also add the number of the pull request where it came from, plus the PR's current status (open, merged (to development versions), closed (i.e. not merged), etc.)

returnValue = functionName(mandatoryParameter, [optionalParameter])

-- This function signature shows how to use the function named "functionName", which parameters to give, etc. More details follow below.

-- The above first line will get scraped to form the auto completion text in Mudlet's editor - Therefore it should try and show the most possible parameters. Sometimes though this may be awkward to do when there are significant alternative forms available. A better method is still to be found.

-- If the function returns no relevant values, drop the equal sign and anything before, otherwise give it a meaningful brief name.

Description of what this function will do. In this case, it is just a non-existing function with the only purpose to show how to write documentation for functions.

-- This will be the second line after the function signature in the first line. (Remember to delete comment lines starting with "--" before publishing this template elsewhere.)

-- The description can be multi-line, but please don't go overboard. You don't need to link to other functions, or explain all parameters in detail, as this will be part of the next sections.

See also

copy(), paste()

-- List a few related functions, so users can cyber around.

-- Make sure to mark the internal links without space characters and with no brackets in the end, whereas the displayed name (after the | sign) should indeed end in () brackets

-- Keep the list curated and don't add every single possible function. Maybe link to one central function hub which itself links to all other variants. Mix existing and new, closely and more loosely related functions. For example, creation / editing / deletion of same items, but only creation of other items (which itself link to their editing & deleting variants)

Available in Mudlet4.11+

-- The version when the functionality is to be introduced should be given (if already known) using this template (assuming a major.minor version number - though a major.minor.patch format may be possible) -- If the code has not been merged yet when documentation begins, please link to the pending PR instead for future reference.

Note: This is an important information

-- You may add several notes if necessary, but please take care not to mark everything as important

Parameters

• mandatoryParameter:

Type and description of this parameter.

• optionalParameter:

(optional) Type and description of this parameter..

-- The optional parameter'S name needn't be telling of its optional status. Relevant is to mark optional parameters at the start of this line (with text "optional" in brackets) and in the function definition line (with [these] brackets)

Returns

• Type and description of whatever the function returns

-- Only keep this section if it does indeed return relevant values

Example

-- a comment explaining what is going on, if there is multiple functionalities (or optional parameters) the examples should start simple and progress in complexity if needed!
-- the examples should be small, but self-contained so new users can copy & paste immediately without going diving in lots other function examples first.
-- comments up top should introduce / explain what it does

local something = function(exampleValue)
if something then
  -- do something with something (assuming there is a meaningful return value)
end

-- maybe another example for the optional second case
local somethingElse = function(exampleValue, anotherValue)

-- lastly, include an example with error handling to give an idea of good practice
local ok, err = function()
if not ok then
  debugc(f"Error: unable to do <particular thing> because {err}\n")
  return
end

Additional development notes

-- This section is not for inclusion when item transferred to final location.

-- It could include revisions or input from other people

-- Please use a signature with timestamp when commenting here. To do that, just type two hyphens '-' followed by four tildes '~' after your comment like so:

Good idea! --~~~~

which will automatically render your user name and current date & time for later reference in the discussion flow.