I was working on the SPI 7-SEG 4DIGIT DISPLAY ARDUINO SHIELD that Ben Jordan created and thought it would be good to have a library based on this Arduino shield. Not only would it be great for developers using this shield, it would be great fun to create this library as well. There is also a couple of great blog post (part 1 and part 2) where Ben describes this project in more detail.
I wanted to create a library that would make it trivially easy to use this 7SEG display shield, so users could write something like this to get started.
But also add some power to it, making it possible to scroll text independently from left/right or right/left on the two different displays, blink individual digits and use the decimal point to mention some features.
From using Arduino and different libraries I know that the libraries that come with the Arduino IDE are installed in the “library” folder of the installation. Libraries that you install yourself, like the one I created here, are installed in the “Documents\Arduino\libraries” folder (for Windows installations that is). This is the same directory as your Arduino “sketchbook directory” when you read your Arduino documentation.
So to start this project I had a look at the Arduino documentation and found Writing a Library for Arduino. This is a great description of how to create a Arduino library and something you should read if your create your own Arduino library. The way Arduino recommend that you document your code is to add comments for each function, variable, loop etc. This is great and something that really helps when you try to understand what the source code does. But there is a way to take this a step further and it costs you almost nothing if you are adding comments to your source code anyway (as all good programmers should! - Ed.). I’m thinking about Doxygen.
If you have not used Doxygen, then this is a quotation from the Doxygen home page to familiarize yourself: “Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.”
Sounds great, doesn’t it? And it is even better than great! It’s awesome!!!
So with the Arduino library documentation, and the documentation from Doxygen, I started the task to create our Seg7Display Arudino library.
Creating a Documented Arduino Library
First I took the example code we had for our first applications for this 7SEG display and created a Seg7Display class. All libraries in Arduino are C++ libraries (or at least they should be) to make it easier for developers to use and also be compatible with existing code and other libraries. A good starting point is to create your constructor and begin() methods. These methods will grow and shrink as you develop, but I find it is good to always update them as the code for the library grows.
I will assume that your know your C++ for the rest of the documentation so I will not go into more details on how the code is constructed and why, but maybe just explain a bit why some of the code is there. There are plenty of different Arduino libraries and examples for those who would like to learn more about C++ and Arduino libraries. Just have a look at the Arduino “Learning” section where most of this is documented.
Anyway, as I code my application I add comments and for these comments to be part of the documentation generated by Doxygen I only need to remember to mark or tag the comments in a specific way. Greatly simplified you just start your comments with “/**”, “/*!” or “///”. As an example I have this comment in for a structure in the Seg7Display class declaration:
This is a simple comment saying that we have a structure called Seg7Display and description of the purpose of the structure. And yes, it could contain more information but for example code I think it works well.
In general a commented block of code contains two pieces of information, a Brief and a Detailed part. These different types will end up at different parts of your generated documentation and this will be clear once you have a look at the generated documentation, but this is an example on how you could addbrief and detailed parts in your comments.
But you can also add much more information. Like for example parameters and return value for methods. For that you would use the tags \param and \return. There is also a \sa (see also) tag that you can use to direct users to other parts of the documentation for more information about whatever part you’re documenting right now. Here is a screenshot of what it could look like:
So this is for the most part what I used to comment the library and I have some screenshots below of what the documentation looks like after it has been generated with Doxygen.
Adding a “Mainpage” to Your Documentation
One thing I also should mention is the \mainpage tag that you can, and probably should, use. This is a tag to tell Doxygen what you want users of your code (or library) to see on the main page of your documentation for it.
As I said in the beginning, Doxygen is a great tool to help you document your code and it is very powerful. What I have described above is more of a teaser and for you who like to start using Doxygen I recommend to have a look at their documentation pages.
Generating the Documentation
Once I felt I was fairly done with the library and I had added my comments (during the coding phase) I used Doxygenwizard to generate my documentation for the library. This is a great self-explaining wizard and at the end you have two options. “Run doxygen” to generate the documentation and “Show HTML output” to view the documentation.
After you run Doxygen you will have an output view with messages containing information on what Doxygen did generate information about and if there were any errors and warnings. It is best of course to fix all errors and warnings before releasing, and this is usually not a problem. Errors must be corrected and most warnings are about parts of your code that Doxygen could not find any documentation or comments about.
Here is a screenshot of the generated main page for the library:
And here is the main document for the Seg7Display class. Each class member is a link to where you will find more information about that member method or variable.
The library with documentation, as well as the SPI 7-SEG 4DIGIT DISPLAY ARDUINO SHIELD project, is available in the CircuitMaker community if you like to have look at the real thing. All is licensed under the CreativeCommons license Attribution 4.0 International, so feel free to use and modify this project for your own application.
Being able to get all of this documentation generated just from documenting your source code is nothing else than amazing! I will polish the library source a bit when I get a chance since I know it could be better, but with the time I got for creating this I think it turned out well. (As a SW developer you are never really done, are you? There is always parts that could be rewritten in a better way.)