How to document a custom library in Arduino

Question

I have created my own library and it is working flawlessly. Now I want to add some documentation to it that the Arduino IDE can understand.

For the functions from the Arduino IDE itself like delay(ms) you can right click them and then select Find in Reference. How can I add this feature to my own library?

Answer 1

Arduino uses the keyword.txt file to highlight words and to define a reference page to keywords. But the reference page must be in reference folder of IDE installation and the keyword.txt contains only a filename, not the path.

REFERENCE_LINK This field specifies the Arduino Language Reference page to open via Right Click > Find in Reference or Help > Find in Reference when the cursor is on that keyword. Generally it does not make sense to define the REFERENCE_LINK field for 3rd party library keywords since they are not likely to be in the Arduino Language Reference.

I have a library which implements WiFiClient and WiFiServer like the Arduino WiFi library, so I can link in keywords.txt to Arduino reference like this:

WiFiClient  KEYWORD2    WiFiClient
WiFiServer  KEYWORD2    WiFiServer
WiFiUDP     KEYWORD2    WiFiUDPConstructor

The names used are names of html files in Arduino\reference\www.arduino.cc\en\Reference.

Answer 2

OK, time for my most comprehensive answer on StackExchange so far (tanks to @Juraj for helping out with this).

To demonstrate all the steps needed for this, this answer will use an example library that will be called Foo.

Here we go:

To add documentation to your library that the Arduino IDE can work with, you first need to place your library in the correct directory. Thats either in your library folder in your sketchbook folder (you can locate it by selecting File>Preferences>Sketchbook location, by default this is

C:\Users\YourUsername\Documents\Arduino\libraries

or

InstallationDirectoryOfYourIDE\portable\sketchbook\libraries

if you are using a portable installation) or in

InstallationDirectoryOfYourIDE\libraries

In which of the two places you put your library is up to you, both work (except if you put in both places at the same time). You should keep this in mind though: If you put your library in the libraries folder of your sketchbook, only you will have access to that library. If there are other users on the same PC that shall be able to use your library, you have to put in in the general libraries folder (if you don't have access to that folder because it belongs to another user and you are not the admin, then too bad, sorry ;).

Your library has to contain at least a file Foo.h which can be located directly in the folder of your library (old standard) or in a subfolder src in your library folder (up to date standard). What the file contains is for the sake of this example absolutely arbitrary (e.g. just leave it empty).

Next you need a valid library.properties file for your library. You can create and edit it with any text editor like notepad. This file has to be placed directly into the folder of the library.

Here is a bare minimum example for this file that works:

name=Foo
version=1.0.0
author=Your name
maintainer=Your name
sentence=Something
paragraph=Whatever
url=http://example.com

More information on how this file works (and other things to consider when creating a library) can be found at the Arduino Library Specification.

Now we can specify which words the IDE shall highlight and which of them shall link to which reference page (to make sure that this works in principle it is not necessary to create your own .html files yet). To do this, create a file keywords.txt in the folder of your library. In it you write something like this:

foo KEYWORD2    Foo

In this example foo is the keyword that will be highlighted in the IDE (and on right click present the option Find in Reference). KEYWORD2 specifies how exactly foo will be highlighted (colour, boldness, etc.), in this case it will appear like normal text in orange (once again, see the Arduino Library Specification for more details on this). Foo is the name of the .html file (without the extension) that is opened when you right click foo in the IDE and select Find in Reference. It has to be located in this folder:

InstallationDirectoryOfYourIDE\reference\www.arduino.cc\en\Reference

The three words are separated by true tabs (not multiple space characters). Before creating your own .html file you can just copy one of the files there and rename it to Foo. Note that your library doesn't have to contain anything else besides the three mentioned files and some file in the reference folder for this to work. At this point you should restart your IDE and check whether your keyword foo is highlighted and offers the option Find in Reference when you right click it. If so, success! You can now move on to create your own .html file to put in the reference folder.

You could start by just changing one of the existent files to fit the style of the Arduino API, but you could also create your entirely own files. The probably best option however is to write your library according to doxygen standards and then let doxygen do the work for you creating the file automatically.

Just one more thing to be mentioned: This method works for any keywords that are used in the way yourKeyword or something.yourKeyword, but not Something::yourKeyword (this is how you would use a static function or variable in your library). According to @Juraj this is something caused by the IDE. There is a workaround for this though: Replace each line in the keywords.txt file

yourKeyword KEYWORDX    ReferenceFile

with

yourKeyword KEYWORDX    ReferenceFile
YourLibrary::yourKeyword    KEYWORDX    ReferenceFile

This way yourKeyword will be highlighted as you would expect it but occurrences like YourLibrary::yourKeyword will also bring up the option Find in Reference when right clicked.

That's it for today. Thanks and bye bye!