Site update: Program documentation, wiki macros

Posted 03 Aug 2010, by Dan Ros

site, updates | 0 replies

A few days ago we released an upgrade to mbed.org. First, the highlights:

You can now see the code of published projects
Published projects come with Doxygen powered documentation
The documentation of published projects is integrated within the mbed wikis

Here's the details of how you can make use of these new features:

See the code of published projects

A feature which has been requested a few times and one which we have wanted to add for a while is quite simple: you can now browse the code of a published project. This lets you get a quick feel for whether a program is worth importing into your Compiler before you do so.

Example of viewing source code

- Example of viewing source code

Published projects come with Doxygen powered documentation

Another powerful feature is that now when you publish programs, any Doxygen compatible markup you insert into your code will be rendered as Doxygen markup within your published program's page. There's too many features of doxygen to go into here, but the main points are:

Documents functions and classes including parameters and return types
Links from documentation about a function or class to the definition in code
Links back from source code to documentation for each documented function or variable

For information on how doxygen markup should look, refer to this cookbook page, or one of the many external guides.

- Example of documentation

The documentation of published projects is integrated within the wikis

Here's where it gets interesting (to me!). Last month we released the new cookbook. This most recent update builds on that by integrating the new program documentation into the wiki engine. Here's what that gets you:

Embed link to a program in any wiki page
Embed summary of program API in any wiki page
Embedded documentation (or code) updates automatically when you update the program

This may sound tricky, but in practice, it's fairly straightforward. All you have to do is put the URL of the documentation into the wikitext.

<<program http://mbed.org/users/aberk/programs/QEI_lib/5ytsc/docs/classQEI.html>>

Results in something like:

Embedded documentation in wiki

- Example of embedded documentation in wiki page

New handbook and future plans

Regular users may also have noticed that at the same time as the above update, the Handbook has updated to the new format. This has the side effect of allowing you to comment on Handbook pages, where your suggestions for improvement of the official documentation is very welcome.

Finally, for those of you still reading, a word on the future plans for the above features.

We will move the Notebooks and the Forum to support the wiki-text method of creating content. This means:

You will be able to use the above features in the notebook and forum
The rich text editor in the forum and notebook will be replaced with a plain text box
You will be able to contribute to the forum from mobile platforms
Getting layout right will hopefully be a lot easier and predictable, without the (sometimes eccentric) rich text editor

No release date on those future plans yet, but they are scheduled in for one of the upcoming releases.

Please log in to post a comment.