Area 51/Template

From Mudlet
Revision as of 14:42, 17 May 2021 by Kebap (talk | contribs)
Jump to navigation Jump to search

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!


functionName

returnValue = functionName(argument1, [optional argument 2])

-- This shows how to use the function named "functionName", which arguments 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 arguments. 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 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)


Note Note: This is an important information

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


Mudlet VersionAvailable in Mudlet4.11.1+

-- The version when the functionality is to be introduced should be given (if already known) using this template (assuming a major.minor.patch version number - though a major.minor format may be sufficient):


Parameters
  • argument1:
Type and description of this argument.
  • argument2:
(optional) Type and description of this argument..

-- This argument name needn't be telling of its optional status. Relevant is to mark optional arguments 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 arguments) 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(argument1)
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(argument1, agrument2)


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.