Improve docs (#373)

Author: andiwand

src/odr/archive.hpp

@@ -11,6 +11,7 @@ class Archive;
 namespace odr {
 class Filesystem;
 
+/// @brief Represents an archive file.
 class Archive {
 public:
   explicit Archive(std::shared_ptr<internal::abstract::Archive>);

src/odr/document.hpp

@@ -15,6 +15,7 @@ class DocumentFile;
 class Element;
 class Filesystem;
 
+/// @brief Represents a document.
 class Document final {
 public:
   explicit Document(std::shared_ptr<internal::abstract::Document>);

src/odr/document_element.hpp

@@ -77,6 +77,7 @@ class Circle;
 class CustomShape;
 class Image;
 
+/// @brief Collection of element types.
 enum class ElementType {
   none,
 
@@ -113,6 +114,7 @@ enum class ElementType {
   group,
 };
 
+/// @brief Collection of anchor types.
 enum class AnchorType {
   as_char,
   at_char,
@@ -121,12 +123,14 @@ enum class AnchorType {
   at_paragraph,
 };
 
+/// @brief Collection of value types.
 enum class ValueType {
   unknown,
   string,
   float_number,
 };
 
+/// @brief Represents an element in a document.
 class Element {
 public:
   Element();
@@ -175,9 +179,10 @@ class Element {
   const internal::abstract::Document *m_document{nullptr};
   internal::abstract::Element *m_element{nullptr};
 
-  bool exists_() const;
+  [[nodiscard]] bool exists_() const;
 };
 
+/// @brief Represents an iterator for elements in a document.
 class ElementIterator {
 public:
   using value_type = Element;
@@ -202,9 +207,10 @@ class ElementIterator {
   const internal::abstract::Document *m_document{nullptr};
   internal::abstract::Element *m_element{nullptr};
 
-  bool exists_() const;
+  [[nodiscard]] bool exists_() const;
 };
 
+/// @brief Represents a range of elements in a document.
 class ElementRange {
 public:
   ElementRange();
@@ -219,6 +225,7 @@ class ElementRange {
   ElementIterator m_end;
 };
 
+/// @brief Represents a typed element in a document.
 template <typename T> class TypedElement : public Element {
 public:
   TypedElement() = default;
@@ -238,9 +245,10 @@ template <typename T> class TypedElement : public Element {
 protected:
   T *m_element;
 
-  bool exists_() const { return m_element != nullptr; }
+  [[nodiscard]] bool exists_() const { return m_element != nullptr; }
 };
 
+/// @brief Represents a root element in a document.
 class TextRoot final : public TypedElement<internal::abstract::TextRoot> {
 public:
   using TypedElement::TypedElement;
@@ -250,6 +258,7 @@ class TextRoot final : public TypedElement<internal::abstract::TextRoot> {
   [[nodiscard]] MasterPage first_master_page() const;
 };
 
+/// @brief Represents a slide element in a document.
 class Slide final : public TypedElement<internal::abstract::Slide> {
 public:
   using TypedElement::TypedElement;
@@ -261,6 +270,7 @@ class Slide final : public TypedElement<internal::abstract::Slide> {
   [[nodiscard]] MasterPage master_page() const;
 };
 
+/// @brief Represents a sheet element in a document.
 class Sheet final : public TypedElement<internal::abstract::Sheet> {
 public:
   using TypedElement::TypedElement;
@@ -278,6 +288,7 @@ class Sheet final : public TypedElement<internal::abstract::Sheet> {
   [[nodiscard]] ElementRange shapes() const;
 };
 
+/// @brief Represents a sheet column element in a document.
 class SheetColumn final : public TypedElement<internal::abstract::Sheet> {
 public:
   SheetColumn() = default;
@@ -290,6 +301,7 @@ class SheetColumn final : public TypedElement<internal::abstract::Sheet> {
   std::uint32_t m_column{};
 };
 
+/// @brief Represents a sheet row element in a document.
 class SheetRow final : public TypedElement<internal::abstract::Sheet> {
 public:
   SheetRow() = default;
@@ -302,6 +314,7 @@ class SheetRow final : public TypedElement<internal::abstract::Sheet> {
   std::uint32_t m_row{};
 };
 
+/// @brief Represents a sheet cell element in a document.
 class SheetCell final : public TypedElement<internal::abstract::SheetCell> {
 public:
   SheetCell() = default;
@@ -316,11 +329,12 @@ class SheetCell final : public TypedElement<internal::abstract::SheetCell> {
   [[nodiscard]] TableCellStyle style() const;
 
 private:
-  internal::abstract::Sheet *m_sheet;
+  internal::abstract::Sheet *m_sheet{};
   std::uint32_t m_column{};
   std::uint32_t m_row{};
 };
 
+/// @brief Represents a page element in a document.
 class Page final : public TypedElement<internal::abstract::Page> {
 public:
   using TypedElement::TypedElement;
@@ -332,20 +346,23 @@ class Page final : public TypedElement<internal::abstract::Page> {
   [[nodiscard]] MasterPage master_page() const;
 };
 
+/// @brief Represents a master page element in a document.
 class MasterPage final : public TypedElement<internal::abstract::MasterPage> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] PageLayout page_layout() const;
 };
 
+/// @brief Represents a line break element in a document.
 class LineBreak final : public TypedElement<internal::abstract::LineBreak> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] TextStyle style() const;
 };
 
+/// @brief Represents a paragraph element in a document.
 class Paragraph final : public TypedElement<internal::abstract::Paragraph> {
 public:
   using TypedElement::TypedElement;
@@ -354,13 +371,15 @@ class Paragraph final : public TypedElement<internal::abstract::Paragraph> {
   [[nodiscard]] TextStyle text_style() const;
 };
 
+/// @brief Represents a span element in a document.
 class Span final : public TypedElement<internal::abstract::Span> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] TextStyle style() const;
 };
 
+/// @brief Represents a text element in a document.
 class Text final : public TypedElement<internal::abstract::Text> {
 public:
   using TypedElement::TypedElement;
@@ -371,27 +390,31 @@ class Text final : public TypedElement<internal::abstract::Text> {
   [[nodiscard]] TextStyle style() const;
 };
 
+/// @brief Represents a link element in a document.
 class Link final : public TypedElement<internal::abstract::Link> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] std::string href() const;
 };
 
+/// @brief Represents a bookmark element in a document.
 class Bookmark final : public TypedElement<internal::abstract::Bookmark> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] std::string name() const;
 };
 
+/// @brief Represents a list item element in a document.
 class ListItem final : public TypedElement<internal::abstract::ListItem> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] TextStyle style() const;
 };
 
+/// @brief Represents a table element in a document.
 class Table final : public TypedElement<internal::abstract::Table> {
 public:
   using TypedElement::TypedElement;
@@ -404,20 +427,23 @@ class Table final : public TypedElement<internal::abstract::Table> {
   [[nodiscard]] TableStyle style() const;
 };
 
+/// @brief Represents a table column element in a document.
 class TableColumn final : public TypedElement<internal::abstract::TableColumn> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] TableColumnStyle style() const;
 };
 
+/// @brief Represents a table row element in a document.
 class TableRow final : public TypedElement<internal::abstract::TableRow> {
 public:
   using TypedElement::TypedElement;
 
   [[nodiscard]] TableRowStyle style() const;
 };
 
+/// @brief Represents a table cell element in a document.
 class TableCell final : public TypedElement<internal::abstract::TableCell> {
 public:
   using TypedElement::TypedElement;
@@ -429,6 +455,7 @@ class TableCell final : public TypedElement<internal::abstract::TableCell> {
   [[nodiscard]] TableCellStyle style() const;
 };
 
+/// @brief Represents a frame element in a document.
 class Frame final : public TypedElement<internal::abstract::Frame> {
 public:
   using TypedElement::TypedElement;
@@ -443,6 +470,7 @@ class Frame final : public TypedElement<internal::abstract::Frame> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
+/// @brief Represents a rectangle element in a document.
 class Rect final : public TypedElement<internal::abstract::Rect> {
 public:
   using TypedElement::TypedElement;
@@ -455,6 +483,7 @@ class Rect final : public TypedElement<internal::abstract::Rect> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
+/// @brief Represents a line element in a document.
 class Line final : public TypedElement<internal::abstract::Line> {
 public:
   using TypedElement::TypedElement;
@@ -467,6 +496,7 @@ class Line final : public TypedElement<internal::abstract::Line> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
+/// @brief Represents a circle element in a document.
 class Circle final : public TypedElement<internal::abstract::Circle> {
 public:
   using TypedElement::TypedElement;
@@ -479,6 +509,7 @@ class Circle final : public TypedElement<internal::abstract::Circle> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
+/// @brief Represents a custom shape element in a document.
 class CustomShape final : public TypedElement<internal::abstract::CustomShape> {
 public:
   using TypedElement::TypedElement;
@@ -491,6 +522,7 @@ class CustomShape final : public TypedElement<internal::abstract::CustomShape> {
   [[nodiscard]] GraphicStyle style() const;
 };
 
+/// @brief Represents an image element in a document.
 class Image final : public TypedElement<internal::abstract::Image> {
 public:
   using TypedElement::TypedElement;

src/odr/document_path.cpp

@@ -50,7 +50,7 @@ DocumentPath::ComponentTemplate<Derived>::to_string() const noexcept {
 
 DocumentPath::Component
 DocumentPath::component_from_string(const std::string &string) {
-  auto colon = string.find(":");
+  auto colon = string.find(':');
   if (colon == std::string::npos) {
     throw std::invalid_argument("string");
   }
@@ -88,11 +88,11 @@ DocumentPath DocumentPath::extract(Element element, Element root) {
     }
 
     if (current.table_column() || current.table_cell()) {
-      reverse.push_back(Column(distance));
+      reverse.emplace_back(Column(distance));
     } else if (current.table_row()) {
-      reverse.push_back(Row(distance));
+      reverse.emplace_back(Row(distance));
     } else {
-      reverse.push_back(Child(distance));
+      reverse.emplace_back(Child(distance));
     }
 
     current = parent;
@@ -145,8 +145,6 @@ bool DocumentPath::operator!=(const DocumentPath &other) const noexcept {
   return m_components != other.m_components;
 }
 
-DocumentPath::operator std::string() const noexcept { return to_string(); }
-
 std::string DocumentPath::to_string() const noexcept {
   std::string result;
 

src/odr/document_path.hpp

@@ -10,14 +10,15 @@ namespace odr {
 class Document;
 class Element;
 
+/// @brief A path to a specific element in a document.
 class DocumentPath final {
 public:
   template <typename Derived> struct ComponentTemplate {
     static const std::string &prefix_string();
 
     std::uint32_t number{0};
 
-    ComponentTemplate(const std::uint32_t number);
+    explicit ComponentTemplate(std::uint32_t number);
 
     bool operator==(const ComponentTemplate &other) const noexcept;
     bool operator!=(const ComponentTemplate &other) const noexcept;
@@ -53,16 +54,14 @@ class DocumentPath final {
   static Element find(Element root, const DocumentPath &path);
 
   DocumentPath() noexcept;
-  DocumentPath(const Container &components);
-  DocumentPath(Container &&components);
-  DocumentPath(const char *c_string);
-  DocumentPath(const std::string &string);
+  explicit DocumentPath(const Container &components);
+  explicit DocumentPath(Container &&components);
+  explicit DocumentPath(const char *c_string);
+  explicit DocumentPath(const std::string &string);
 
   bool operator==(const DocumentPath &other) const noexcept;
   bool operator!=(const DocumentPath &other) const noexcept;
 
-  operator std::string() const noexcept;
-
   [[nodiscard]] std::string to_string() const noexcept;
 
   [[nodiscard]] bool empty() const noexcept;
@@ -80,4 +79,4 @@ class DocumentPath final {
 
 } // namespace odr
 
-#endif // ODR_INTERNAL_COMMON_DOCUMENT_PATH_HPP
+#endif // ODR_DOCUMENT_PATH_HPP