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
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
if you are using a portable installation) or in
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:
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:
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
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
yourKeyword KEYWORDX ReferenceFile
yourKeyword KEYWORDX ReferenceFile
YourLibrary::yourKeyword KEYWORDX ReferenceFile
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!