Setting up 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: In the translator, create a new directory, call it MyLibrary

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

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

STEP 4: Click on EDIT to open the edit screen

1. Give it a description of your choice.

2. Add a parameter name and a description.

3. Select the “DOES THE FUNCTION TAKE A SINGLE TABLE ARGUMENT?” option next to Parameters and click Save.

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

To have this help file show up in auto-completion, we now have to map it to the help system.

1. Create a file called mappings.lua in MyLibrary directory

2. Define a lua table called Methods - this is a table of methods our help system will reference

local Methods = {};   

3. 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   

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

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

5. 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}   

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 6: 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 7: 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: