From 907b5fed58d53bbb5e25c590df97f01a0ac93733 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Sun, 8 Nov 2009 10:08:52 +0200
Subject: Implement option documentation support in frontend

---
 cli/parser.cxx            | 45 +++++++++++++++++++++++++++++++++++++++++++++
 cli/semantics/option.hxx  | 31 +++++++++++++++++++++++++++++++
 doc/language.txt          | 13 ++++++++++---
 tests/parser/makefile     |  2 +-
 tests/parser/test-006.cli | 16 ++++++++++++++++
 tests/parser/test-006.std |  0
 6 files changed, 103 insertions(+), 4 deletions(-)
 create mode 100644 tests/parser/test-006.cli
 create mode 100644 tests/parser/test-006.std

diff --git a/cli/parser.cxx b/cli/parser.cxx
index 55c609a..639ddf4 100644
--- a/cli/parser.cxx
+++ b/cli/parser.cxx
@@ -532,6 +532,51 @@ option_def (token& t)
     unit_->new_edge<initialized> (*o, e);
   }
 
+  if (t.punctuation () == token::p_lcbrace)
+  {
+    // doc-string-seq
+    //
+    for (t = lexer_->next ();; t = lexer_->next ())
+    {
+      if (t.type () != token::t_string_lit)
+      {
+        cerr << *path_ << ':' << t.line () << ':' << t.column () << ": error: "
+             << "expected documentation string instead of " << t << endl;
+        throw error ();
+      }
+
+      if (valid_)
+      {
+        // Get rid of '"'.
+        //
+        string r;
+        string const& l (t.literal ());
+
+        for (size_t i (0), n (l.size ()); i < n; ++i)
+        {
+          if (l[i] != '"' || (i != 0 && l[i - 1] == '\\'))
+            r += l[i];
+        }
+
+        o->doc ().push_back (r);
+      }
+
+      t = lexer_->next ();
+
+      if (t.punctuation () != token::p_comma)
+        break;
+    }
+
+    if (t.punctuation () != token::p_rcbrace)
+    {
+      cerr << *path_ << ':' << t.line () << ':' << t.column () << ": error: "
+           << "expected '}' instead of " << t << endl;
+      throw error ();
+    }
+
+    t = lexer_->next ();
+  }
+
   if (t.punctuation () != token::p_semi)
   {
     cerr << *path_ << ':' << t.line () << ':' << t.column () << ": error: "
diff --git a/cli/semantics/option.hxx b/cli/semantics/option.hxx
index d5437e1..a4f34d0 100644
--- a/cli/semantics/option.hxx
+++ b/cli/semantics/option.hxx
@@ -6,6 +6,8 @@
 #ifndef CLI_SEMANTICS_OPTION_HXX
 #define CLI_SEMANTICS_OPTION_HXX
 
+#include <vector>
+
 #include <semantics/elements.hxx>
 
 namespace semantics
@@ -136,6 +138,34 @@ namespace semantics
     }
 
   public:
+    typedef std::vector<string> doc_list;
+    typedef doc_list::const_iterator doc_iterator;
+
+    doc_iterator
+    doc_begin () const
+    {
+      return doc_.begin ();
+    }
+
+    doc_iterator
+    doc_end () const
+    {
+      return doc_.end ();
+    }
+
+    doc_list const&
+    doc () const
+    {
+      return doc_;
+    }
+
+    doc_list&
+    doc ()
+    {
+      return doc_;
+    }
+
+  public:
     option (path const& file, size_t line, size_t column)
         : node (file, line, column), initialized_ (0)
     {
@@ -156,6 +186,7 @@ namespace semantics
   private:
     belongs_type* belongs_;
     initialized_type* initialized_;
+    doc_list doc_;
   };
 }
 
diff --git a/doc/language.txt b/doc/language.txt
index 865a4d3..46bb753 100644
--- a/doc/language.txt
+++ b/doc/language.txt
@@ -17,7 +17,7 @@ def-unit:
 
 include-decl-seq:
 	include-decl
-	include-decl-seq include-decl;
+	include-decl-seq include-decl
 
 include-decl:
 	"include" path-literal ";"
@@ -44,7 +44,7 @@ option-def-seq:
 	option-def-seq option-def
 
 option-def:
-	type-spec option-name-seq initializer(opt) ";"
+	type-spec option-name-seq initializer(opt) option-doc ";"
 
 type-spec:
 	fundamental-type-spec
@@ -52,7 +52,7 @@ type-spec:
 
 option-name-seq:
 	option-name
-	option-name-seq "|" option-name;
+	option-name-seq "|" option-name
 
 option-name:
 	option-identifier
@@ -71,6 +71,13 @@ initializer-expr:
 	qualified-name
         call-expr
 
+option-doc:
+	"{" doc-string-seq "}"
+
+doc-string-seq:
+	string-literal
+	doc-string-seq "," string-literal
+
 qualified-name:
 	"::" qualified-name-trailer
 	qualified-name-trailer
diff --git a/tests/parser/makefile b/tests/parser/makefile
index c64e496..2d435b4 100644
--- a/tests/parser/makefile
+++ b/tests/parser/makefile
@@ -7,7 +7,7 @@ include $(dir $(lastword $(MAKEFILE_LIST)))../../build/bootstrap.make
 
 cxx_tun := driver.cxx
 
-tests := 000 001 002 003 004 005
+tests := 000 001 002 003 004 005 006
 
 #
 #
diff --git a/tests/parser/test-006.cli b/tests/parser/test-006.cli
new file mode 100644
index 0000000..5b555e4
--- /dev/null
+++ b/tests/parser/test-006.cli
@@ -0,0 +1,16 @@
+// option-doc
+//
+class c
+{
+  bool --help | -h {"Help me"};
+
+  int --comp = 5
+  {
+    "<level>",
+    "Set compression level",
+    "Set compression level to <level>.
+
+     The minimum value for this options is 0 and
+     maximum is 9."
+  };
+};
diff --git a/tests/parser/test-006.std b/tests/parser/test-006.std
new file mode 100644
index 0000000..e69de29
-- 
cgit v1.1