Pokitto Guidebook (WIP) on pokitto.github.io

Pokitto Guidebook (Work in Progress)

With a fantastic contribution from @bl_ackrain , we have begun the construction of a better guidebook for Pokitto.

The guidebook uses Github pages and anyone can help in making the guidebook better by editing and contributing on Github

The guidebook can be seen here:

https://pokitto.github.io/

Editing and adding content can be done here, at the repository:

7 Likes

Will the API reference be updated to use Doxygen at some point?

Yes. I plan on writing the Doxygen comments properly.

In fact, if you could give some advice on how to comment so that we get the best results, that advice would be very much appreciated.

1 Like

I will certainly put this on my ‘to do’ list,
and hopefully I’ll be contributing some new documentation when I have chance.
But it will probably have to come after my magazine contribution otherwise I run the risk of putting that off and getting behind.

(I probably won’t have chance to do anything until the weekend though, this week has been quite busy for me.)

You could look at what I did for the Arduboy2 library code (mostly the header files) and the resulting output to get some ideas.

2 Likes

@MLXXXp’s suggestion is good - Arduboy2’s documentation is demonstrates many of the core Doxygen keywords (e.g. /brief), as well as some of the more ‘detailed’ ones (e.g. /return and /param), and also demonstrates an exceptional level of detail/coverage.

There’s also my sequel library prototype,
which demonstrates a very minimalist use of Doxygen comments.
(So minimalist that if I hadn’t told you they generate valid ‘brief’ and ‘detailed’ Doxygen descriptions you might not even notice they weren’t ordinary comments.)
(There’s a good example here.)
Unfortunately I don’t have pregenerated Doxygen for that,
but I can generate some upon request.

And the Doxygen comments I (and I would presume @FManga) provided for Femto’s Java API.
(There’s a good example here).
The generated output should be somewhere, but I’m not sure quite where,
so I’ll point you to the old copy that I generated myself.
Note especially that there are code examples included with the documentation.

Also note that Doxygen can be set to recognise markdown, as well as HTML tags like <sup></sup>,
so presentation can be very flexible.


One last thing I’d like to mention quickly (though I think I’ve mentioned it before),
is that I think it’s better to use single-line Doxygen comments (e.g. /// or //!) rather than multiline comments.

Aside from the fact they look more uniform, I think they’re easier to add to and shuffle around because you don’t have to worry about aligning asterisks or dealing with start and end markers (/* and */).
Also you can just add an extra / to your normal single-line comments and then worry about adding Doxygen-specific keywords/directives later.

Comparison:

/*!
* \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
 
/// \brief Brief description.
/// Brief description continued.
///
/// Detailed description starts here.

I like the design of the guide book overall. Plus being a github pages makes it so anyone can contribute to it, while still having moderators review any changes before they go live.

Plus there isn’t much needed in the way of planning out all the sections it should have, because as people add things to the guidebook it will naturally expand and grow.

1 Like

I’ve just thrown together a ‘cheatsheet’ containing some of the more common doxygen commands (and a few particularly interesting commands).

This isn’t a replacement for the documentation,
but it’s a more friendly quick reference that makes it easier to become aware of the various commands because they’re grouped by category rather than being kept in an alphabetical list.

The cheatsheet itself is here and there’s a handful of examples here.

This isn’t enough information to generate documentation,
but it’s enough to help people who want to contribute documentation understand what kind of information can be documented.


I did have a quick look at the library source code earlier to see if I could document something,
but most of what I found was undocumented I realised I don’t actually have the knowledge to document.

2 Likes