How to document a custom library in Arduino
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
.
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 tab
s (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!