Improve code documentation for symbols

(bzr r12324)

1 files changed, 19 insertions, 2 deletions

diff --git a/src/ui/dialog/symbols.h b/src/ui/dialog/symbols.h
index b81f6981e..352d24ec0 100644
--- a/src/ui/dialog/symbols.h
+++ b/src/ui/dialog/symbols.h
@@ -2,9 +2,10 @@
  * @brief Symbols dialog
  */
 /* Authors:
- *   Tavmjong Bah
+ *   Tavmjong Bah, Martin Owens
  *
  * Copyright (C) 2012 Tavmjong Bah
+ *               2013 Martin Owens
  *
  * Released under GNU GPL, read the file 'COPYING' for more information
  */
@@ -29,7 +30,23 @@ namespace Dialog {
 class SymbolColumns; // For Gtk::ListStore
 
 /**
- * A dialog that displays selectable symbols.
+ * A dialog that displays selectable symbols and allows users to drag or paste
+ * those symbols from the dialog into the document.
+ *
+ * Symbol documents are loaded from the preferences paths and displayed in a
+ * drop-down list to the user. The user then selects which of the symbols
+ * documents they want to get symbols from. The first document in the list is
+ * always the current document.
+ *
+ * This then updates an icon-view with all the symbols available. Selecting one
+ * puts it onto the clipboard. Dragging it or pasting it onto the canvas copies
+ * the symbol from the symbol document, into the current document and places a
+ * new <use element at the correct location on the canvas.
+ *
+ * Selected groups on the canvas can be added to the current document's symbols
+ * table, and symbols can be removed from the current document. This allows
+ * new symbols documents to be constructed and if saved in the prefs folder will
+ * make those symbols available for all future documents.
  */
 class SymbolsDialog : public UI::Widget::Panel {