Setting Up Custom Help For An Object with Methods

Sometimes you might want help for methods on an object.

For instance our database library returns a database connection object that has methods with help. Iguana’s help system makes it possible to register help for these methods also.

Another example would be say you were writing a library which acts as an adapter like a “Salesforce” adapter - you authenticate and get a salesforce object that has methods on it to do things with the sales force API. Here’s some imaginary code:

local S = SALESconnect{user='fred', password=Secret}
local List = S:listCustomers{filter="ABC*"}
S:addCustomer{name="Acme", description="A generic company"}

This outlines the process:

STEP 1: Create a component and enter the translator

You probably have done this a million times now. I believe in you 😅

STEP 2: Create a new directory, call it MyLibrary

STEP 3: Create a file within that directory, call it plus1, and be sure to select the .help extension

STEP 4: Click on the new file and the Help editor will open up, it will be mostly blank

STEP 5: Click on the 3 dot menu to open the edit screen

Give it a description of your choice.
Add a parameter name and a description.
- Select the “DOES THE FUNCTION TAKE A SINGLE TABLE ARGUMENT?” option next to Parameters:
Click SAVE

STEP 6: Now we have to map it to the help system, create mappings.lua file.

To have this help file show up in autocompletion we now have to map it to the help system.
Create a file called mappings.lua in MyLibrary directory
Define a lua table called Methods – this is a table of methods our help system will reference

local Methods = {};

Copy and paste the function below, which references the help file we edited:

function iguana.plus1(T)
   if (T.number) then
      return T.number + 1
   end
end

We will now add this function to our Methods table by using the following code:

Methods.plus1 = iguana.plus1 -- map method for help

Finally, we call help.map, which takes a table with two arguments, dir and methods dir will be the directory MyLibrary we created, and methods will be our Methods table

-- map help for all functions
help.map{dir='MyLibrary',methods=Methods}

STEP 7: mappings.lua full file

The final code should look like the below:

local Methods = {};

function iguana.plus1(T)
   if (T.number) then
      return T.number + 1
   end
end
Methods.plus1 = iguana.plus1 -- map method for help

-- map help for all functions
help.map{dir='MyLibrary',methods=Methods}

STEP 8: Go back to main.lua file and enter require statement

Finally, at the top of your main.lua file we have to import the help library we just created via the mappings file

require "MyLibrary.mappings"

STEP 9: Access the help by the translator autocompletion functionality

Now, test to see if you get autocompletion for your new custom function by typing the below in the main function in main.lua.
To bring up the help page test by following the screenshot below:

Add line 4 in the screenshot by typing it out using the autocompletion feature in Iguana. It should look like below: