Install Optional Self-Documentation Tools

This section requires embedXcode+ and is optional.

The installation of the following tools is optional and only required if you want to use the self-documentation feature.

  • Doxygen generates all the help files based on comments added to the code. Doxygen requires Graphviz to draw elaborate dependency trees.

  • Doxygen Helper provides a handy shortcut to add a ready-to-use template for comments.

  • TeXShop translates the Doxygen output into PDF documents.

  • Artistic Style is a utility to indent, format and improve the presentation of the code.

Install Doxygen

Install Doxygen  to parse the code, looks for comments and generate the HTML pages.

Doxygen generates HTML files, Xcode native help files and LateX files. LateX files can be converted into PDF documents using TeXShop.

I strongly recommend to install DoxyWizard included in the package.

DoxyWizard provides a GUI for an easy tweaking of the parameters.

Install Graphviz

Install Graphviz to add dependency trees.

Graphviz  is no longer available as a package for macOS. Instead, the installation relies on Homebrew.

To install Graphviz,

  • Open a Terminal window.

  • If Homebrew  isn't installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Run the following command to install graphiz.
$ brew install graphviz

The latest package available is Graphviz  2.36 for OS X 10.8 Mountain Lion. Learn more at the Mac OS dedicated page .

However, Graphviz requires X11, which is no longer included with OS X 10.8 Mountain Lion.

In a technical note , Apple recommends to use XQuartz  instead.

Install Doxygen Helper

To ease and speed up the writing of the comments, I use the Automator Service Doxygen Helper .

By just selecting a function and pressing Cmd+Shift+D, the helper generates a template for the comment lines.

///
/// @brief   Blink a LED
/// @details LED attached to pin is light on off
/// @n       Total cycle duration = ms
/// @param   pin pin to which the LED is attached
/// @param   times number of times
/// @param   ms cycle duration in ms
///
void blink(uint8_t pin, uint8_t times, uint16_t ms);

A modified version of the Automator Service is included in the ~/Documents/embedXcode folder. To install it:

  • Unzip the automator_service_xcode_modified file.

  • Double-click on the Document Code workflow.

A window pops-up and asks for confirmation:

  • Confirm by clicking on Install.

  • Optionally, click on Open with Automator to launch Automator and edit the service.

However, if you prefer to install the original Automator Service,

The previously recommended alternative, the ThisService  utility, is no longer available.

Install TeXShop

Finally, TeXShop builds a PDF document from the LateX files Doxygen has generated.

To install TeXshop,

  • Download TeXShop as a standalone application, or

  • Download TeXShop and other utilities including fonts as part of the MacTeX-2016 full distribution.

embedXcode supports the 2015 and 2016 distributions of MacTeX. MacTeX-2016 is recommended as some users reported issues with MacTeX-2015.

  • Launch the installation package and follow the instructions.

Below, an example of a LateX file translated into a PDF document.

Install Artistic Style

Artistic Style is a utility to indent, format and improve the presentation of the code.

For more information about the options,

  • Please refer to the Documentation page on the Artistic Style website.

It is a good idea to launch this utility before sharing the code.

To install Artistic Style,

  • Open a Terminal window.

  • If Homebrew  isn't installed, launch the following command.

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  • Run the following command to install Artistic Style.
$ brew install astyle