Document how to use clang-format (#92)

moveit · Oct 17, 2016 · be729a8 · be729a8
1 parent 449d959
commit be729a8
Showing 1 changed file with 45 additions and 1 deletion.
diff --git a/documentation/contributing/code.markdown b/documentation/contributing/code.markdown
@@ -11,7 +11,7 @@ title: Style Guidelines
 
 We use the [ROS C++ Style guide](http://wiki.ros.org/CppStyleGuide) for all C++ development and the [ROS Python Style guide](http://wiki.ros.org/PyStyleGuide) for Python.
 
-To ease your development, we recommend the automated code formatter ``clang-format`` with a ROS configuration found [here](https://github.com/davetcoleman/roscpp_code_format)
+To ease your development, we recommend the automated code formatter ``clang-format`` with a ROS configuration - to use see below.
 
 In addition MoveIt! has some extra style preferences:
 
@@ -40,3 +40,47 @@ MoveIt! uses *one* folder for all headers from all of its modules: ``include/mov
 
 This is rather non-standard for catkin - catkin would prefer to have headers of each ROS package in a separate folder,
 e.g. `include/moveit_core/...`, `include/moveit_ros_planning/...`, etc.
+
+## clang-format Auto Code Formatting
+
+
+You can run **clang-format** in several ways:
+
+### Command Line
+
+Format single file:
+
+    clang-format-3.6 -i -style=file MY_ROS_NODE.cpp
+
+Format entire directory recursively including subfolders:
+
+    find . -name '*.h' -or -name '*.hpp' -or -name '*.cpp' | xargs clang-format-3.6 -i -style=file $1
+
+### Emacs Editor Configuration
+
+In your ``~/.emacs`` config file, add the following:
+
+Format your source code if its in some directory such as the ``catkin_ws`` (feel free to change keywords catkin_ws):
+
+```
+(defun run-ros-clang-format ()
+"Runs clang-format on cpp,h files in catkin_ws/ and reverts buffer."
+(interactive)
+(and
+(string-match "/catkin_ws/.*\\.\\(h\\|cpp\\)$" buffer-file-name)
+(save-some-buffers 'no-confirm)
+(shell-command (concat "clang-format-3.6 -style=file -i " buffer-file-name))
+(message (concat "Saved and ran clang-format on " buffer-file-name))
+(revert-buffer t t t)
+))
+```
+
+Set a keyboard shortcut to run, such as F12
+
+    (global-set-key [f12] 'run-ros-clang-format)
+
+### Atom Editor Configuration
+
+Install the [clang-format](https://atom.io/packages/clang-format) package via the Atom package manager or ``apm install clang-format``.
+
+In the package settings set ``clang-format-3.6`` as your executable and point 'Style' to your ``.clang-format`` file.