update sample docs

adobe · Jul 12, 2023 · 504802e · 504802e
1 parent 3c86c1a
commit 504802e
Show file tree

Hide file tree

Showing 66 changed files with 1,783 additions and 3 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,5 +6,3 @@ build/
 build*/
 docs/_site/
 docs/Gemfile.lock
-docs/libraries
-!docs/libraries/index.md
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -12,7 +12,7 @@ email: [email protected]
 baseurl: /hyde
 url: "https://opensource.adobe.com/" # the base hostname & protocol for your site
 repository: adobe/hyde
-remote_theme: adobe/hyde-theme@develop
+remote_theme: adobe/hyde-theme@v2.0.0
 exclude:
     - "*.sh"
     - vendor # For Travis-CI (see https://jekyllrb.com/docs/continuous-integration/)

diff --git a/docs/libraries/classes.cpp/class_example/color.md b/docs/libraries/classes.cpp/class_example/color.md
@@ -0,0 +1,31 @@
+---
+layout: enumeration
+title: color
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - enumeration
+  inline:
+    brief: an example enumeration within the class.
+    description:
+      - Note that nested classes will not inherit their ownership from the class that contains them, so thus need their own `hyde-owner`.
+    owner: sean-parent
+  defined_in_file: classes.cpp
+  values:
+    - description: __INLINED__
+      inline:
+        description:
+          - this is an example description for the `red` value.
+      name: red
+    - description: __INLINED__
+      inline:
+        description:
+          - this is an example description for the `green` value.
+      name: green
+    - description: __INLINED__
+      inline:
+        description:
+          - this is an example description for the `blue` value.
+      name: blue
+---
diff --git a/docs/libraries/classes.cpp/class_example/index.md b/docs/libraries/classes.cpp/class_example/index.md
@@ -0,0 +1,60 @@
+---
+layout: class
+title: class_example
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - class
+  inline:
+    brief: an example class that demonstrates what Hyde documents.
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  declaration: "\nclass class_example;"
+  dtor: unspecified
+  typedefs:
+    typedef_example:
+      definition: std::string
+      description: __INLINED__
+      inline:
+        description:
+          - a nested `typedef` expression.
+    using_example:
+      definition: std::string
+      description: __INLINED__
+      inline:
+        description:
+          - a nested `using` expression.
+  fields:
+    _deprecated_member:
+      annotation:
+        - private
+        - deprecated("example deprecation message")
+      description: __INLINED__
+      inline:
+        description:
+          - a deprecated member variable that contains a message. Apparently this works?!
+      type: int
+    _nested:
+      annotation:
+        - private
+      description: __INLINED__
+      inline:
+        description:
+          - an instance of the nested class example defined earlier.
+      type: class_example::nested_class_example
+    _static_member:
+      description: __INLINED__
+      inline:
+        description:
+          - static member variable.
+      type: const int
+    _x:
+      annotation:
+        - private
+      description: __INLINED__
+      inline:
+        description:
+          - some variable that holds an integer.
+      type: int
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_class_example.md b/docs/libraries/classes.cpp/class_example/m_class_example.md
@@ -0,0 +1,36 @@
+---
+layout: method
+title: class_example
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief: _multiple descriptions_
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  is_ctor: true
+  overloads:
+    class_example():
+      annotation:
+        - defaulted
+      description: __INLINED__
+      inline:
+        description:
+          - default constructor.
+      signature_with_names: class_example()
+    explicit class_example(int):
+      arguments:
+        - description: __OPTIONAL__
+          name: x
+          type: int
+      description: __INLINED__
+      inline:
+        arguments:
+          x:
+            description: The one integer parameter this routine takes
+        description:
+          - an explicit constructor that takes a single `int`.
+      signature_with_names: explicit class_example(int x)
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_deprecated.md b/docs/libraries/classes.cpp/class_example/m_deprecated.md
@@ -0,0 +1,36 @@
+---
+layout: method
+title: deprecated
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief:
+      - deprecated member function.
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  overloads:
+    void deprecated(const std::string &, class_example *):
+      annotation:
+        - deprecated
+      arguments:
+        - description: __OPTIONAL__
+          name: first
+          type: const std::string &
+        - description: __OPTIONAL__
+          name: second
+          type: class_example *
+      description: __INLINED__
+      inline:
+        arguments:
+          first:
+            description: the first parameter
+          second:
+            description: the second parameter
+        description:
+          - deprecated member function.
+      return: __OPTIONAL__
+      signature_with_names: void deprecated(const std::string & first, class_example * second)
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_deprecated_with_message.md b/docs/libraries/classes.cpp/class_example/m_deprecated_with_message.md
@@ -0,0 +1,36 @@
+---
+layout: method
+title: deprecated_with_message
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief:
+      - deprecated member function that contains a compile-time deprecation message.
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  overloads:
+    void deprecated_with_message(const std::string &, class_example *):
+      annotation:
+        - deprecated("example deprecation message")
+      arguments:
+        - description: __OPTIONAL__
+          name: s
+          type: const std::string &
+        - description: __OPTIONAL__
+          name: f
+          type: class_example *
+      description: __INLINED__
+      inline:
+        arguments:
+          f:
+            description: the second parameter
+          s:
+            description: the first parameter
+        description:
+          - deprecated member function that contains a compile-time deprecation message.
+      return: __OPTIONAL__
+      signature_with_names: void deprecated_with_message(const std::string & s, class_example * f)
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_member_function.md b/docs/libraries/classes.cpp/class_example/m_member_function.md
@@ -0,0 +1,23 @@
+---
+layout: method
+title: member_function
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief:
+      - example member function.
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  overloads:
+    int member_function():
+      description: __INLINED__
+      inline:
+        description:
+          - example member function.
+        return: double the value of `_x`.
+      return: __OPTIONAL__
+      signature_with_names: int member_function()
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_member_function_trailing_return_type.md b/docs/libraries/classes.cpp/class_example/m_member_function_trailing_return_type.md
@@ -0,0 +1,23 @@
+---
+layout: method
+title: member_function_trailing_return_type
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief:
+      - member function with a trailing return type.
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  overloads:
+    auto member_function_trailing_return_type() const -> int:
+      description: __INLINED__
+      inline:
+        description:
+          - member function with a trailing return type.
+        return: "\"`_x`\""
+      return: __OPTIONAL__
+      signature_with_names: auto member_function_trailing_return_type() const -> int
+---
diff --git a/docs/libraries/classes.cpp/class_example/m_overloaded.md b/docs/libraries/classes.cpp/class_example/m_overloaded.md
@@ -0,0 +1,131 @@
+---
+layout: method
+title: overloaded
+hyde:
+  owner: __INLINED__
+  brief: __INLINED__
+  tags:
+    - method
+  inline:
+    brief: _multiple descriptions_
+    owner: fosterbrereton
+  defined_in_file: classes.cpp
+  overloads:
+    void overloaded():
+      annotation:
+        - deprecated
+      description: __INLINED__
+      inline:
+        description:
+          - a deprecated overload that takes zero parameters.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded()
+    void overloaded(const std::string &):
+      arguments:
+        - description: __OPTIONAL__
+          name: first
+          type: const std::string &
+      description: __INLINED__
+      inline:
+        arguments:
+          first:
+            description: the first parameter of the first overload.
+        brief: A series of overloaded functions.
+        description:
+          - an overloaded member function that takes one parameter.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded(const std::string & first)
+    void overloaded(const std::string &, class_example *, int):
+      arguments:
+        - description: __OPTIONAL__
+          name: unnamed-0
+          type: const std::string &
+          unnamed: true
+        - description: __OPTIONAL__
+          name: unnamed-1
+          type: class_example *
+          unnamed: true
+        - description: __OPTIONAL__
+          name: unnamed-2
+          type: int
+          unnamed: true
+      description: __INLINED__
+      inline:
+        description:
+          - an overloaded member function that takes three unnamed parameters. Let it be known that Doxygen doesn't support documenting unnamed parameters at this time. There is a [bug open on the issue](https://github.com/doxygen/doxygen/issues/6926), but as of this writing does not appear to be progressing.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded(const std::string &, class_example *, int)
+    void overloaded(const std::string &, class_example *, int, bool, std::size_t):
+      arguments:
+        - description: __OPTIONAL__
+          name: first
+          type: const std::string &
+        - description: __OPTIONAL__
+          name: second
+          type: class_example *
+        - description: __OPTIONAL__
+          name: third
+          type: int
+        - description: __OPTIONAL__
+          name: fourth
+          type: bool
+        - description: __OPTIONAL__
+          name: fifth
+          type: std::size_t
+      description: __INLINED__
+      inline:
+        arguments:
+          fifth:
+            description: the fifth parameter of the fourth overload.
+          first:
+            description: the first parameter of the fourth overload.
+          fourth:
+            description: the fourth parameter of the fourth overload.
+          second:
+            description: the second parameter of the fourth overload.
+          third:
+            description: the third parameter of the fourth overload.
+        description:
+          - an overloaded member function that takes _five_ parameters.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded(const std::string & first, class_example * second, int third, bool fourth, std::size_t fifth)
+    void overloaded(const std::string &, const std::string &) volatile:
+      arguments:
+        - description: __OPTIONAL__
+          name: first
+          type: const std::string &
+        - description: __OPTIONAL__
+          name: second
+          type: const std::string &
+      description: __INLINED__
+      inline:
+        arguments:
+          first:
+            description: the first parameter of the second overload.
+          second:
+            description: the second parameter of the second overload.
+        brief: Another brief describing one of the overloaded functions.
+        description:
+          - an overloaded member function that takes two parameters.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded(const std::string & first, const std::string & second) volatile
+    void overloaded(const std::string &, std::vector<int>) const:
+      arguments:
+        - description: __OPTIONAL__
+          name: first
+          type: const std::string &
+        - description: __OPTIONAL__
+          name: second
+          type: std::vector<int>
+      description: __INLINED__
+      inline:
+        arguments:
+          first:
+            description: the first parameter of the third overload.
+          second:
+            description: the second parameter of the third overload.
+        description:
+          - another overloaded member function that takes two parameters.
+      return: __OPTIONAL__
+      signature_with_names: void overloaded(const std::string & first, std::vector<int> second) const
+---