Parse documentation comments

include/cppast/cpp_class.hpp

@@ -165,6 +165,12 @@ namespace cppast
                 class_->add_child(std::move(child));
             }
 
+            /// \returns The not yet finished class.
+            cpp_class& get() noexcept
+            {
+                return *class_;
+            }
+
             /// \effects Registers the class in the [cppast::cpp_entity_index](),
             /// using the given [cppast::cpp_entity_id]().
             /// \returns The finished class.

include/cppast/cpp_entity.hpp

@@ -50,6 +50,44 @@ namespace cppast
             return parent_;
         }
 
+        /// \returns The documentation comment associated with that entity, if any.
+        /// \notes A documentation comment can have three forms:
+        ///
+        /// * A C style doc comment. It is a C style comment starting with an additional `*`, i.e. `/**`.
+        /// One space after the leading sequence will be skipped.
+        /// It ends either with `*/` or `**/`.
+        /// After a newline all whitespace is skipped, as well as an optional `*` followed by another optional space,
+        /// as well as trailing whitespace on each line.
+        /// I.e. `/** a\n      * b */` yields the text `a\nb`.
+        /// * A C++ style doc comment. It is a C++ style comment starting with an additional `/` or '!`,
+        /// i.e. `///` or `//!`.
+        /// One space character after the leading sequence will be skipped,
+        /// as well as any trailing whitespace.
+        /// Two C++ style doc comments on two adjacent lines will be merged.
+        /// * An end of line doc comment. It is a C++ style comment starting with an '<', i.e. `//<`.
+        /// One space character after the leading sequence will be skipped,
+        /// as well as any trailing whitespace.
+        /// If the next line is a C++ style doc comment, it will be merged with that one.
+        ///
+        /// A documentation comment is associated with an entity,
+        /// if for C and C++ style doc comments, the entity declaration begins
+        /// on the line after the last line of the comment,
+        /// and if for an end of line comment, the entity declaration ends
+        /// on the same line as the end of line comment.
+        ///
+        /// This comment system is also used by [standardese](https://standardese.foonathan.net).
+        type_safe::optional_ref<const std::string> comment() const noexcept
+        {
+            return comment_.empty() ? nullptr : type_safe::opt_ref(&comment_);
+        }
+
+        /// \effects Sets the associated comment.
+        /// \requires The comment must not be empty, if there is one.
+        void set_comment(type_safe::optional<std::string> comment) noexcept
+        {
+            comment_ = std::move(comment.value());
+        }
+
     protected:
         /// \effects Creates it giving it the the name.
         cpp_entity(std::string name) : name_(std::move(name))
@@ -72,8 +110,9 @@ namespace cppast
             parent_ = parent;
         }
 
-        type_safe::optional_ref<const cpp_entity> parent_;
         std::string                               name_;
+        std::string                               comment_;
+        type_safe::optional_ref<const cpp_entity> parent_;
 
         template <typename T>
         friend struct detail::intrusive_list_access;

include/cppast/cpp_enum.hpp

@@ -76,6 +76,12 @@ namespace cppast
                 enum_->add_child(std::move(value));
             }
 
+            /// \returns The not yet finished enumeration.
+            cpp_enum& get() noexcept
+            {
+                return *enum_;
+            }
+
             /// \effects Registers the enum in the [cppast::cpp_entity_index](),
             /// using the given [cppast::cpp_entity_id]().
             /// \returns The finished enum.

include/cppast/cpp_file.hpp

@@ -5,6 +5,8 @@
 #ifndef CPPAST_CPP_FILE_HPP_INCLUDED
 #define CPPAST_CPP_FILE_HPP_INCLUDED
 
+#include <vector>
+
 #include <cppast/cpp_entity_index.hpp>
 #include <cppast/cpp_entity_container.hpp>
 #include <cppast/cpp_entity_ref.hpp>
@@ -17,6 +19,8 @@ namespace cppast
     class cpp_file final : public cpp_entity, public cpp_entity_container<cpp_file, cpp_entity>
     {
     public:
+        static cpp_entity_kind kind() noexcept;
+
         /// Builds a [cppast::cpp_file]().
         class builder
         {
@@ -32,6 +36,18 @@ namespace cppast
                 file_->add_child(std::move(child));
             }
 
+            /// \effects Adds an unmatched documentation comment.
+            void add_unmatched_comment(std::string str)
+            {
+                file_->comments_.push_back(std::move(str));
+            }
+
+            /// \returns The not yet finished file.
+            cpp_file& get() noexcept
+            {
+                return *file_;
+            }
+
             /// \effects Registers the file in the [cppast::cpp_entity_index]().
             /// It will use the file name as identifier.
             /// \returns The finished file.
@@ -45,6 +61,12 @@ namespace cppast
             std::unique_ptr<cpp_file> file_;
         };
 
+        /// \returns The unmatched documentation comments.
+        type_safe::array_ref<const std::string> unmatched_comments() const noexcept
+        {
+            return type_safe::ref(comments_.data(), comments_.size());
+        }
+
     private:
         cpp_file(std::string name) : cpp_entity(std::move(name))
         {
@@ -52,6 +74,8 @@ namespace cppast
 
         /// \returns [cpp_entity_type::file_t]().
         cpp_entity_kind do_get_entity_kind() const noexcept override;
+
+        std::vector<std::string> comments_;
     };
 
     /// \exclude

include/cppast/cpp_function.hpp

@@ -122,6 +122,12 @@ namespace cppast
                 static_cast<cpp_function_base&>(*function).noexcept_expr_ = std::move(cond);
             }
 
+            /// \returns The not yet finished function.
+            T& get() noexcept
+            {
+                return *function;
+            }
+
             /// \effects If the body is a definition, registers it.
             /// Else marks it as a declaration.
             /// \returns The finished function.

include/cppast/cpp_language_linkage.hpp

@@ -32,6 +32,12 @@ namespace cppast
                 linkage_->add_child(std::move(child));
             }
 
+            /// \returns The not yet finished language linkage.
+            cpp_language_linkage& get() const noexcept
+            {
+                return *linkage_;
+            }
+
             /// \returns The finalized language linkage.
             /// \notes It is not registered on purpose as nothing can refer to it.
             std::unique_ptr<cpp_language_linkage> finish()

include/cppast/cpp_namespace.hpp

@@ -35,6 +35,12 @@ namespace cppast
                 namespace_->add_child(std::move(child));
             }
 
+            /// \returns The not yet finished namespace.
+            cpp_namespace& get() const noexcept
+            {
+                return *namespace_;
+            }
+
             /// \effects Registers the namespace in the [cppast::cpp_entity_index](),
             /// using the given [cppast::cpp_entity_id]().
             /// \returns The finished namespace.