Difference between revisions of "Area 51/Template"
m |
m (→See also: add () brackets to the displayed name) |
||
(17 intermediate revisions by 3 users not shown) | |||
Line 7: | Line 7: | ||
Remember to generally strip out each comment line before publishing a new documentation! | 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: | ||
+ | # headline | ||
+ | # function signature | ||
+ | # description | ||
+ | # see also | ||
+ | # mudlet version | ||
+ | # note | ||
+ | # parameters | ||
+ | # returns | ||
+ | # example | ||
+ | # additional notes for developers, etc. | ||
==functionName== | ==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]) | ||
− | -- 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 | + | -- 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. | -- If the function returns no relevant values, drop the equal sign and anything before, otherwise give it a meaningful brief name. | ||
Line 26: | Line 47: | ||
− | See also: | + | ;See also: [[Manual:Lua_Functions#copy|copy()]], [[Manual:Lua_Functions#paste|paste()]] |
− | [[Manual:Lua_Functions#copy|copy]], | ||
− | [[Manual:Lua_Functions#paste|paste]] | ||
-- List a few related functions, so users can cyber around. | -- List a few related functions, so users can cyber around. | ||
Line 34: | Line 53: | ||
-- 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 | -- 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) | + | -- 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) |
− | {{ | + | {{MudletVersion|4.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 | ;Parameters | ||
− | * '' | + | * ''mandatoryParameter:'' |
− | : Type and description of this | + | : Type and description of this parameter. |
− | * '' | + | * ''optionalParameter:'' |
− | : (optional) Type and description of this | + | : (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) |
Line 64: | Line 84: | ||
;Example | ;Example | ||
<syntaxhighlight lang="lua"> | <syntaxhighlight lang="lua"> | ||
− | -- | + | -- 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( | + | local something = function(exampleValue) |
if something then | if something then | ||
− | -- | + | -- do something with something (assuming there is a meaningful return value) |
end | end | ||
− | -- | + | -- maybe another example for the optional second case |
− | local somethingElse = function( | + | 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 | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
; Additional development notes | ; Additional development notes |
Latest revision as of 01:25, 2 April 2023
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:
- headline
- function signature
- description
- see also
- mudlet version
- note
- parameters
- returns
- example
- 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.
-- 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)
-- 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.