Improve documentation

generator/codefactory.cpp

@@ -25,6 +25,10 @@ CodeFactory::ToolInvocation::ToolInvocation(CodeFactory &factory)
     fileManager.Retain();
 }
 
+/*!
+ * \brief Constructs a new instance.
+ * \remarks The specified arguments are not copied and must remain valid for the live-time of the code factory.
+ */
 CodeFactory::CodeFactory(
     const char *applicationPath, const std::vector<const char *> &sourceFiles, const std::vector<string> &clangOptions, std::ostream &os)
     : m_applicationPath(applicationPath)

generator/codefactory.h

@@ -57,43 +57,73 @@ private:
     clang::CompilerInstance *m_compilerInstance;
 };
 
+/*!
+ * \brief Instantiates a code generator of the specified type and adds it to the current instance.
+ * \remarks The specified \a args are forwarded to the generator's constructor.
+ */
 template <typename GeneratorType, typename... Args> void CodeFactory::addGenerator(Args &&... args)
 {
     m_generators.emplace_back(std::make_unique<GeneratorType>(*this, std::forward<Args>(args)...));
 }
 
 namespace Detail {
+/*!
+ * \brief Wraps const references using std::cref() for use with std::bind().
+ */
 template <typename T> std::reference_wrapper<const T> wrapReferences(const T &val)
 {
     return std::cref(val);
 }
 
+/*!
+ * \brief Wraps mutable references using std::ref() for use with std::bind().
+ */
 template <typename T> std::reference_wrapper<T> wrapReferences(T &val)
 {
     return std::ref(val);
 }
 
+/*!
+ * \brief Forwards non-references for use with std::bind().
+ */
 template <typename T> T &&wrapReferences(T &&val)
 {
     return std::forward<T>(val);
 }
 } // namespace Detail
 
+/*!
+ * \brief Returns a function which instantiates a code generator of the specified type and adds it to the current instance.
+ * \remarks
+ * - The specified \a args are forwarded to the generator's constructor.
+ * - No copy of \a args passed by reference is made.
+ */
 template <typename GeneratorType, typename... Args> auto CodeFactory::bindGenerator(Args &&... args)
 {
     return std::bind(&CodeFactory::addGenerator<GeneratorType, Args...>, this, Detail::wrapReferences(std::forward<Args>(args)...));
 }
 
+/*!
+ * \brief Returns the added generators.
+ */
 inline const std::vector<std::unique_ptr<CodeGenerator>> &CodeFactory::generators() const
 {
     return m_generators;
 }
 
+/*!
+ * \brief Returns the compiler instance.
+ * \remarks The is nullptr for a newly constructed factory and should be assigned by the frontend action.
+ */
 inline clang::CompilerInstance *CodeFactory::compilerInstance()
 {
     return m_compilerInstance;
 }
 
+/*!
+ * \brief Assigns the compiler instance.
+ * \remarks The factory does *not* take ownership.
+ */
 inline void CodeFactory::setCompilerInstance(clang::CompilerInstance *compilerInstance)
 {
     m_compilerInstance = compilerInstance;

generator/consumer.cpp

@@ -57,7 +57,7 @@ void DiagConsumer::finish()
 }
 
 /*!
- * \brief Turns most errors into warnings so it works despite issues when parsing libstdc++ headers.
+ * \brief Turns most errors into warnings so the code generator can even work when parsing incomplete headers.
  */
 void DiagConsumer::HandleDiagnostic(clang::DiagnosticsEngine::Level diagLevel, const clang::Diagnostic &info)
 {

generator/consumer.h

@@ -16,7 +16,7 @@ class CodeFactory;
 /*!
  * \brief The Consumer class is passed to FrontendAction for handling occurrences of different elements of the file.
  *
- * These elements consist of top-level declarations, namespace definitions and most imporantly the whole translation unit.
+ * These elements consist of top-level declarations, namespace definitions and most importantly the whole translation unit.
  * If the translations unit has occurred, that means nested elements (eg. classes) have been read completely.
  * In this case, the Consumer class will trigger traversing the translation unit using a Visitor instance.
  */
@@ -45,7 +45,7 @@ inline Consumer::Consumer(CodeFactory &factory, clang::CompilerInstance &compile
 }
 
 /*!
- * \brief The DiagConsumer class changes most errors into warnings.
+ * \brief The DiagConsumer class allows turning most errors into warnings.
  * \remarks This class is based on MocDiagConsumer from https://github.com/woboq/moc-ng.
  */
 class DiagConsumer : public clang::DiagnosticConsumer {
@@ -70,6 +70,9 @@ inline DiagConsumer::DiagConsumer(std::unique_ptr<clang::DiagnosticConsumer> Pre
 {
 }
 
+/*!
+ * \brief Returns the number of errors which actually would have been occurred if we would not turn most errors into warnings.
+ */
 inline unsigned int DiagConsumer::realErrorCount() const
 {
     return m_realErrorCount;