├── docs ├── serve.sh ├── favicon.ico ├── about.md ├── libraries │ ├── enums.cpp │ │ ├── index.md │ │ ├── untyped.md │ │ └── color_channel.md │ ├── point.cpp │ │ ├── index.md │ │ └── point3CT3E │ │ │ ├── m_origin.md │ │ │ ├── index.md │ │ │ ├── m_operator-3D.md │ │ │ ├── f_operator3D3D.md │ │ │ ├── f_operator213D.md │ │ │ ├── f_operator-.md │ │ │ └── m_point3CT3E.md │ ├── classes.cpp │ │ ├── index.md │ │ ├── specialization_example3CT3E │ │ │ ├── m_as_tuple.md │ │ │ └── index.md │ │ ├── specialization_example3Cfloat3E │ │ │ ├── m_as_tuple.md │ │ │ └── index.md │ │ ├── class_example │ │ │ ├── nested_class_example │ │ │ │ ├── m_~nested_class_example.md │ │ │ │ ├── index.md │ │ │ │ └── m_nested_class_example.md │ │ │ ├── m_member_function.md │ │ │ ├── m_static_method.md │ │ │ ├── m_member_function_trailing_return_type.md │ │ │ ├── m_template_member_function.md │ │ │ ├── color.md │ │ │ ├── m_class_example.md │ │ │ ├── m_deprecated.md │ │ │ ├── m_deprecated_with_message.md │ │ │ ├── index.md │ │ │ └── m_overloaded.md │ │ ├── specialization_example3.ed9d8cc7 │ │ │ ├── m_as_tuple.md │ │ │ └── index.md │ │ ├── partial_specialization_.4b7bfe45 │ │ │ └── index.md │ │ └── partial_specialization_.edfbc14d │ │ │ └── index.md │ ├── comments.cpp │ │ ├── index.md │ │ ├── compiler_generated │ │ │ ├── index.md │ │ │ ├── m_operator3D.md │ │ │ ├── m_assign.md │ │ │ └── m_compiler_generated.md │ │ ├── some_other_struct │ │ │ ├── m_~some_other_struct.md │ │ │ ├── index.md │ │ │ ├── m_virtual_function.md │ │ │ ├── m_some_other_struct.md │ │ │ └── m_operator3D.md │ │ ├── some_struct │ │ │ ├── m_~some_struct.md │ │ │ ├── m_virtual_function.md │ │ │ ├── m_some_struct.md │ │ │ ├── m_operator3D.md │ │ │ ├── index.md │ │ │ └── m_some_function.md │ │ └── f_template_function.md │ ├── functions.cpp │ │ ├── index.md │ │ ├── f_nullary_function_example.md │ │ ├── f_static_function_example.md │ │ ├── f_static_auto_function_example.md │ │ ├── f_static_trailing_type_function_example.md │ │ ├── f_binary_function_example.md │ │ ├── f_template_function_example.md │ │ └── f_overloaded.md │ ├── namespaces.cpp │ │ ├── index.md │ │ └── f_function.md │ ├── index.md │ └── typedef_and_alias.cpp │ │ ├── template_example3CT2C20U3E │ │ └── index.md │ │ ├── template_example_instantiator │ │ └── index.md │ │ └── index.md ├── _posts │ └── 2018-10-30-welcome.markdown ├── _sass │ ├── _overrides-dark.scss │ ├── _overrides-light.scss │ └── _overrides.scss ├── Gemfile ├── index.html ├── _config.yml ├── feed.xml ├── _includes │ └── head.html └── images │ └── site │ └── hyde.svg ├── .gitignore ├── include ├── _clang_include_suffix.hpp ├── _clang_include_prefix.hpp ├── json.hpp ├── json_fwd.hpp ├── config.hpp ├── autodetect.hpp └── output_yaml.hpp ├── .hyde-config ├── .gitmodules ├── .github ├── PULL_REQUEST_TEMPLATE │ ├── bug_fix.md │ └── feature.md ├── ISSUE_TEMPLATE │ ├── feature_request.md │ └── bug_report.md └── workflows │ └── tagged-release.yml ├── .editorconfig ├── generate_test_files.sh ├── LICENSE ├── matchers ├── matcher_fwd.hpp ├── namespace_matcher.cpp ├── enum_matcher.hpp ├── class_matcher.hpp ├── function_matcher.hpp ├── typedef_matcher.hpp ├── namespace_matcher.hpp ├── typealias_matcher.hpp ├── typedef_matcher.cpp ├── typealias_matcher.cpp ├── function_matcher.cpp ├── enum_matcher.cpp ├── utilities.hpp └── class_matcher.cpp ├── test_files ├── enums.cpp ├── namespaces.cpp ├── functions.cpp ├── point.cpp ├── typedef_and_alias.cpp ├── comments.cpp └── classes.cpp ├── emitters ├── yaml_enum_emitter.hpp ├── yaml_class_emitter.hpp ├── yaml_library_emitter.hpp ├── yaml_function_emitter.hpp ├── yaml_sourcefile_emitter.hpp ├── yaml_library_emitter.cpp ├── yaml_base_emitter_fwd.hpp ├── yaml_sourcefile_emitter.cpp ├── yaml_enum_emitter.cpp └── yaml_class_emitter.cpp ├── CONTRIBUTING.md ├── Dockerfile ├── CODE_OF_CONDUCT.md ├── .clang-format ├── sources ├── output_yaml.cpp └── autodetect.cpp ├── CMakeLists.txt └── README.md /docs/serve.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | bundle exec jekyll serve --watch 4 | -------------------------------------------------------------------------------- /docs/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/adobe/hyde/HEAD/docs/favicon.ico -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.sublime-project 2 | *.sublime-workspace 3 | .DS_Store 4 | .vscode/ 5 | build/ 6 | build*/ 7 | docs/_site/ 8 | docs/Gemfile.lock 9 | -------------------------------------------------------------------------------- /docs/about.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | title: About 4 | tab: About 5 | permalink: /about/ 6 | --- 7 | 8 | This is the about page. There are many like it, but this one is mine. 9 | -------------------------------------------------------------------------------- /include/_clang_include_suffix.hpp: -------------------------------------------------------------------------------- 1 | #if __clang__ 2 | #pragma clang diagnostic pop 3 | #elif __GNUC__ // must follow clang (which defines both) 4 | #pragma GCC diagnostic pop 5 | #endif 6 | -------------------------------------------------------------------------------- /.hyde-config: -------------------------------------------------------------------------------- 1 | { 2 | "hyde-src-root" : "./test_files", 3 | "hyde-yaml-dir" : "./docs/libraries", 4 | "clang_flags": [ 5 | "--std=c++2a", 6 | "-Wno-everything" 7 | ] 8 | } 9 | -------------------------------------------------------------------------------- /docs/libraries/enums.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: enums.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: point.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: classes.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: comments.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: functions.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /docs/libraries/namespaces.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: namespaces.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | --- 11 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "submodules/yaml-cpp"] 2 | path = submodules/yaml-cpp 3 | url = https://github.com/jbeder/yaml-cpp.git 4 | [submodule "submodules/json"] 5 | path = submodules/json 6 | url = https://github.com/nlohmann/json.git 7 | -------------------------------------------------------------------------------- /docs/_posts/2018-10-30-welcome.markdown: -------------------------------------------------------------------------------- 1 | --- 2 | layout: post 3 | title: Welcome! 4 | excerpt_separator: 5 | --- 6 | 7 | This is the landing page for the `hyde` sample files example site. Poke around in the `Libraries` section, above. 8 | -------------------------------------------------------------------------------- /docs/libraries/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: Hyde Sample Docs 4 | hyde: 5 | owner: fosterbrereton 6 | brief: Sample Hyde Documentation 7 | tags: 8 | - library 9 | library-type: library 10 | icon: book 11 | short_title: Sample Docs 12 | tab: Docs 13 | --- 14 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/bug_fix.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug fix 3 | about: Submit a fix for an issue 4 | --- 5 | 6 | **Fix for issue(s)** 7 | #NNNN 8 | 9 | **Diagnosis** 10 | Please include a brief description of the root cause, and the fix(es) applied. 11 | 12 | **Additional notes** 13 | Add any other context about the problem here. 14 | 15 | _Thank you!_ 16 | -------------------------------------------------------------------------------- /.editorconfig: -------------------------------------------------------------------------------- 1 | # According to https://stackoverflow.com/a/33831598/153535, this should improve 2 | # the way code is seen on GitHub (PRs, etc.) by making it respect tabs as being 3 | # four spaces. 4 | 5 | root = true 6 | 7 | # Matches multiple files with brace expansion notation 8 | [*.{c,cc,cpp,cxx,h,hh,hpp,hxx,mm}] 9 | indent_style = space 10 | indent_size = 4 11 | -------------------------------------------------------------------------------- /docs/_sass/_overrides-dark.scss: -------------------------------------------------------------------------------- 1 | // Copy this file to you site and use it to override CSS variables that apply to the dark CSS 2 | // definitions. See `main-dark.scss` in the theme for a complete list of variables you can override 3 | // with this file. 4 | 5 | // @debug "Old link-color: #{$link-color}"; 6 | // $hyde-primary: $stlab-purple; 7 | // $link-color: $stlab-purple; 8 | // @debug "New link-color: #{$link-color}"; 9 | -------------------------------------------------------------------------------- /docs/_sass/_overrides-light.scss: -------------------------------------------------------------------------------- 1 | // Copy this file to you site and use it to override CSS variables that apply to the light CSS 2 | // definitions. See `main-light.scss` in the theme for a complete list of variables you can override 3 | // with this file. 4 | 5 | // @debug "Old hyde-primary: #{$link-color}"; 6 | // $hyde-primary: $stlab-purple; 7 | // $link-color: $stlab-purple; 8 | // @debug "New link-color: #{$link-color}"; 9 | -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE/feature.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature 3 | about: Provide new functionality 4 | --- 5 | 6 | **Optional: Related issue(s)** 7 | #NNNN 8 | 9 | **What's Changed** 10 | A clear and concise description of what's included in this PR. 11 | 12 | **Rationale** 13 | A clear and concise description of why this change is valuable. 14 | 15 | **Additional context** 16 | Add any other context here. 17 | 18 | _Thank you!_ 19 | -------------------------------------------------------------------------------- /docs/Gemfile: -------------------------------------------------------------------------------- 1 | source "https://rubygems.org" 2 | 3 | # Manage our dependency on the version of the github-pages gem here. 4 | gem "github-pages", "= 228" 5 | 6 | # Explicitly include this gem here. 7 | # It is not directly included in the github-pages gem list of dependencies, 8 | # even though it is included in the original GitHub Pages build infrastructure. 9 | gem "jekyll-include-cache", "= 0.2.1" 10 | gem "jekyll-octicons", "~> 14.2" 11 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/compiler_generated/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: compiler_generated 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: Sample class intended to exhibit docs for compiler-generated routines 11 | owner: fosterbrereton 12 | defined_in_file: comments.cpp 13 | declaration: "\nstruct compiler_generated;" 14 | dtor: unspecified 15 | --- 16 | -------------------------------------------------------------------------------- /docs/_sass/_overrides.scss: -------------------------------------------------------------------------------- 1 | // Copy this file to you site and use it to override CSS variables that apply to both the light and 2 | // dark CSS definitions, such as font families, content widths, etc. See `_main.scss` in the theme 3 | // for a complete list of variables you can override with this file. 4 | 5 | // @debug "Old base-font-family: #{$base-font-family}"; 6 | // $base-font-family: "Georgia"; 7 | // @debug "New base-font-family: #{$base-font-family}"; 8 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_other_struct/m_~some_other_struct.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: ~some_other_struct 4 | hyde: 5 | owner: __OPTIONAL__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | defined_in_file: comments.cpp 10 | is_dtor: true 11 | overloads: 12 | ~some_other_struct(): 13 | annotation: 14 | - implicit 15 | description: __OPTIONAL__ 16 | signature_with_names: ~some_other_struct() 17 | --- 18 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3CT3E/m_as_tuple.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: as_tuple 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __MISSING__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: classes.cpp 12 | overloads: 13 | constexpr auto as_tuple() const: 14 | description: __OPTIONAL__ 15 | return: __OPTIONAL__ 16 | signature_with_names: constexpr auto as_tuple() const 17 | --- 18 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/m_~some_struct.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: ~some_struct 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: comments.cpp 12 | is_dtor: true 13 | overloads: 14 | ~some_struct(): 15 | annotation: 16 | - deleted 17 | description: __OPTIONAL__ 18 | signature_with_names: ~some_struct() 19 | --- 20 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3CT3E/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: specialization_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example template class with some specializations 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "template \nstruct specialization_example;" 14 | ctor: unspecified 15 | dtor: unspecified 16 | --- 17 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3Cfloat3E/m_as_tuple.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: as_tuple 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __MISSING__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: classes.cpp 12 | overloads: 13 | constexpr tuple as_tuple() const: 14 | description: __OPTIONAL__ 15 | return: __OPTIONAL__ 16 | signature_with_names: constexpr tuple as_tuple() const 17 | --- 18 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/nested_class_example/m_~nested_class_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: ~nested_class_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: sean-parent 11 | defined_in_file: classes.cpp 12 | is_dtor: true 13 | overloads: 14 | ~nested_class_example(): 15 | annotation: 16 | - implicit 17 | description: __OPTIONAL__ 18 | signature_with_names: ~nested_class_example() 19 | --- 20 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_other_struct/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: some_other_struct 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: This is a sample brief for `some_other_struct` 11 | description: 12 | - Notice how many of the comments for this structure are inherited from its superclass. 13 | defined_in_file: comments.cpp 14 | declaration: "\nstruct some_other_struct;" 15 | ctor: unspecified 16 | dtor: unspecified 17 | --- 18 | -------------------------------------------------------------------------------- /include/_clang_include_prefix.hpp: -------------------------------------------------------------------------------- 1 | #if __clang__ 2 | #pragma clang diagnostic push 3 | #pragma clang diagnostic ignored "-Wunknown-pragmas" 4 | #pragma clang diagnostic ignored "-Wall" 5 | #pragma clang diagnostic ignored "-Weverything" 6 | #elif __GNUC__ // must follow clang (which defines both) 7 | #pragma GCC diagnostic push 8 | #pragma GCC diagnostic ignored "-Wdeprecated-enum-enum-conversion" 9 | #pragma GCC diagnostic ignored "-Wunknown-pragmas" 10 | #pragma GCC diagnostic ignored "-Wall" 11 | #pragma GCC diagnostic ignored "-Wextra" 12 | #endif 13 | -------------------------------------------------------------------------------- /docs/libraries/namespaces.cpp/f_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: function 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: _multiple descriptions_ 11 | defined_in_file: namespaces.cpp 12 | overloads: 13 | void function(): 14 | description: __INLINED__ 15 | inline: 16 | description: 17 | - function contained within namespace `foo`. 18 | return: __OPTIONAL__ 19 | signature_with_names: void function() 20 | namespace: 21 | - foo 22 | - bar 23 | - baz 24 | --- 25 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/f_template_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: template_function 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: some template function 11 | defined_in_file: comments.cpp 12 | overloads: 13 | "template \nT template_function()": 14 | description: __OPTIONAL__ 15 | inline: 16 | brief: some template function 17 | return: an instance of type `T` 18 | return: __OPTIONAL__ 19 | signature_with_names: "template \nT template_function()" 20 | --- 21 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_other_struct/m_virtual_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: virtual_function 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - A virtual function that intends to be overridden. 12 | defined_in_file: comments.cpp 13 | overloads: 14 | void virtual_function(): 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - A virtual function that intends to be overridden. 19 | return: __OPTIONAL__ 20 | signature_with_names: void virtual_function() 21 | --- 22 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_nullary_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: nullary_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - an example nullary function. 12 | defined_in_file: functions.cpp 13 | overloads: 14 | int nullary_function_example(): 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - an example nullary function. 19 | return: "`0`" 20 | return: __OPTIONAL__ 21 | signature_with_names: int nullary_function_example() 22 | --- 23 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_static_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: static_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - an example static function 12 | defined_in_file: functions.cpp 13 | overloads: 14 | static int static_function_example(): 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - an example static function 19 | return: "`0`" 20 | return: __OPTIONAL__ 21 | signature_with_names: static int static_function_example() 22 | --- 23 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_member_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: member_function 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - example member function. 12 | owner: fosterbrereton 13 | defined_in_file: classes.cpp 14 | overloads: 15 | int member_function(): 16 | description: __INLINED__ 17 | inline: 18 | description: 19 | - example member function. 20 | return: double the value of `_x`. 21 | return: __OPTIONAL__ 22 | signature_with_names: int member_function() 23 | --- 24 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/m_origin.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: origin 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - A static routine that returns the origin point. 12 | defined_in_file: point.cpp 13 | overloads: 14 | constexpr static auto origin(): 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - A static routine that returns the origin point. 19 | return: The point `(0, 0)` 20 | return: __OPTIONAL__ 21 | signature_with_names: constexpr static auto origin() 22 | --- 23 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/m_virtual_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: virtual_function 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - A virtual function that intends to be overridden. 12 | owner: fosterbrereton 13 | defined_in_file: comments.cpp 14 | overloads: 15 | void virtual_function(): 16 | description: __INLINED__ 17 | inline: 18 | description: 19 | - A virtual function that intends to be overridden. 20 | return: __OPTIONAL__ 21 | signature_with_names: void virtual_function() 22 | --- 23 | -------------------------------------------------------------------------------- /include/json.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // nlohmann/json 15 | #include "nlohmann/json.hpp" 16 | 17 | // application 18 | #include "json_fwd.hpp" 19 | 20 | /**************************************************************************************************/ 21 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | 5 | --- 6 | 7 | **Is your feature request related to a problem? Please describe.** 8 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 9 | 10 | **Describe the solution you'd like** 11 | A clear and concise description of what you want to happen. 12 | 13 | **Describe alternatives you've considered** 14 | A clear and concise description of any alternative solutions or features you've considered. 15 | 16 | **Additional context** 17 | Add any other context or screenshots about the feature request here. 18 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_static_method.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: static_method 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: static member function. 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | overloads: 14 | static int static_method(): 15 | description: __OPTIONAL__ 16 | inline: 17 | brief: static member function. 18 | return: Zero. By which I mean `0`. In the sources, this comment is on multiple lines. 19 | return: __OPTIONAL__ 20 | signature_with_names: static int static_method() 21 | --- 22 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/m_some_struct.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: some_struct 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: comments.cpp 12 | is_ctor: true 13 | overloads: 14 | some_struct(const some_struct &): 15 | annotation: 16 | - implicit 17 | arguments: 18 | - description: __OPTIONAL__ 19 | name: unnamed-0 20 | type: const some_struct & 21 | unnamed: true 22 | description: __OPTIONAL__ 23 | signature_with_names: some_struct(const some_struct &) 24 | --- 25 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: point 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: An example point class 11 | defined_in_file: point.cpp 12 | declaration: "template \nstruct point;" 13 | dtor: unspecified 14 | fields: 15 | x: 16 | description: __INLINED__ 17 | inline: 18 | description: 19 | - The `x` coordinate of the point. 20 | type: T 21 | y: 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - The `y` coordinate of the point. 26 | type: T 27 | --- 28 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3.ed9d8cc7/m_as_tuple.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: as_tuple 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - An example function 12 | owner: fosterbrereton 13 | defined_in_file: classes.cpp 14 | overloads: 15 | constexpr tuple as_tuple() const: 16 | description: __INLINED__ 17 | inline: 18 | description: 19 | - An example function 20 | return: a tuple of the fields of this class 21 | return: __OPTIONAL__ 22 | signature_with_names: constexpr tuple as_tuple() const 23 | --- 24 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/m_operator3D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: operator= 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: comments.cpp 12 | overloads: 13 | some_struct & operator=(const some_struct &): 14 | annotation: 15 | - implicit 16 | arguments: 17 | - description: __OPTIONAL__ 18 | name: unnamed-0 19 | type: const some_struct & 20 | unnamed: true 21 | description: __OPTIONAL__ 22 | return: __OPTIONAL__ 23 | signature_with_names: some_struct & operator=(const some_struct &) 24 | --- 25 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_static_auto_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: static_auto_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - an example static function with `auto` return type 12 | defined_in_file: functions.cpp 13 | overloads: 14 | static int static_auto_function_example(): 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - an example static function with `auto` return type 19 | return: "`0`" 20 | return: __OPTIONAL__ 21 | signature_with_names: static int static_auto_function_example() 22 | --- 23 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/partial_specialization_.4b7bfe45/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: partial_specialization_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example `int, T` partial specialization 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "\nclass partial_specialization_example;" 14 | ctor: unspecified 15 | dtor: unspecified 16 | fields: 17 | _first: 18 | annotation: 19 | - private 20 | description: __MISSING__ 21 | type: std::string 22 | _second: 23 | annotation: 24 | - private 25 | description: __MISSING__ 26 | type: T 27 | --- 28 | -------------------------------------------------------------------------------- /docs/libraries/enums.cpp/untyped.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: enumeration 3 | title: untyped 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - enumeration 9 | inline: 10 | brief: An example untyped enumeration with three values. 11 | owner: fosterbrereton 12 | defined_in_file: enums.cpp 13 | values: 14 | - description: __INLINED__ 15 | inline: 16 | description: 17 | - Apple commentary 18 | name: apple 19 | - description: __INLINED__ 20 | inline: 21 | description: 22 | - Orange commentary 23 | name: orange 24 | - description: __INLINED__ 25 | inline: 26 | description: 27 | - Banana commentary 28 | name: banana 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_static_trailing_type_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: static_trailing_type_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - an example static function with trailing return type 12 | defined_in_file: functions.cpp 13 | overloads: 14 | static auto static_trailing_type_function_example() -> int: 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - an example static function with trailing return type 19 | return: "`0`" 20 | return: __OPTIONAL__ 21 | signature_with_names: static auto static_trailing_type_function_example() -> int 22 | --- 23 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/compiler_generated/m_operator3D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: operator= 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: comments.cpp 12 | overloads: 13 | constexpr compiler_generated & operator=(const compiler_generated &): 14 | annotation: 15 | - implicit 16 | arguments: 17 | - description: __OPTIONAL__ 18 | name: unnamed-0 19 | type: const compiler_generated & 20 | unnamed: true 21 | description: __OPTIONAL__ 22 | return: __OPTIONAL__ 23 | signature_with_names: constexpr compiler_generated & operator=(const compiler_generated &) 24 | --- 25 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_member_function_trailing_return_type.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: member_function_trailing_return_type 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - member function with a trailing return type. 12 | owner: fosterbrereton 13 | defined_in_file: classes.cpp 14 | overloads: 15 | auto member_function_trailing_return_type() const -> int: 16 | description: __INLINED__ 17 | inline: 18 | description: 19 | - member function with a trailing return type. 20 | return: "\"`_x`\"" 21 | return: __OPTIONAL__ 22 | signature_with_names: auto member_function_trailing_return_type() const -> int 23 | --- 24 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/partial_specialization_.edfbc14d/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: partial_specialization_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example template class with a partial specialization. 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "template \nclass partial_specialization_example;" 14 | ctor: unspecified 15 | dtor: unspecified 16 | fields: 17 | _first: 18 | annotation: 19 | - private 20 | description: __MISSING__ 21 | type: T1 22 | _second: 23 | annotation: 24 | - private 25 | description: __MISSING__ 26 | type: T2 27 | --- 28 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3Cfloat3E/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: specialization_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example `float` specialization 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "\nstruct specialization_example;" 14 | ctor: unspecified 15 | dtor: unspecified 16 | typedefs: 17 | value_type: 18 | definition: float 19 | description: __MISSING__ 20 | fields: 21 | _first: 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - An example field used in `as_tuple` 26 | type: specialization_example::value_type 27 | --- 28 | -------------------------------------------------------------------------------- /docs/libraries/enums.cpp/color_channel.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: enumeration 3 | title: color_channel 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - enumeration 9 | inline: 10 | brief: An example typed enumeration with three values. 11 | owner: fosterbrereton 12 | defined_in_file: enums.cpp 13 | values: 14 | - description: __INLINED__ 15 | inline: 16 | description: 17 | - Red commentary 18 | name: red 19 | - description: __INLINED__ 20 | inline: 21 | description: 22 | - Green commentary. Note this enum has a pre-set value. 23 | name: green 24 | - description: __INLINED__ 25 | inline: 26 | description: 27 | - Blue commentary 28 | name: blue 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/typedef_and_alias.cpp/template_example3CT2C20U3E/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: template_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: Example class with two type definitions 11 | defined_in_file: typedef_and_alias.cpp 12 | declaration: "template \nstruct template_example;" 13 | ctor: unspecified 14 | dtor: unspecified 15 | typedefs: 16 | typedef_from_T: 17 | definition: T 18 | description: __INLINED__ 19 | inline: 20 | description: 21 | - Type derived from the first template parameter. 22 | using_from_U: 23 | definition: U 24 | description: __INLINED__ 25 | inline: 26 | description: 27 | - Type derived from the second template parameter. 28 | --- 29 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/specialization_example3.ed9d8cc7/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: specialization_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example `std::int32` specialization 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "\nstruct specialization_example;" 14 | ctor: unspecified 15 | dtor: unspecified 16 | typedefs: 17 | value_type: 18 | definition: std::int32_t 19 | description: __INLINED__ 20 | inline: 21 | description: 22 | - An example typedef 23 | fields: 24 | _first: 25 | description: __INLINED__ 26 | inline: 27 | description: 28 | - An example field used in `as_tuple` 29 | type: specialization_example::value_type 30 | --- 31 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/compiler_generated/m_assign.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: assign 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - This definition will force the compiler to auto-generate this class' assignment operator. 12 | owner: fosterbrereton 13 | defined_in_file: comments.cpp 14 | overloads: 15 | void assign(const compiler_generated &): 16 | arguments: 17 | - description: __OPTIONAL__ 18 | name: rhs 19 | type: const compiler_generated & 20 | description: __INLINED__ 21 | inline: 22 | description: 23 | - This definition will force the compiler to auto-generate this class' assignment operator. 24 | return: __OPTIONAL__ 25 | signature_with_names: void assign(const compiler_generated & rhs) 26 | --- 27 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: some_struct 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: This is a sample brief. 11 | description: 12 | - An example struct from which these commands will hang. 13 | owner: fosterbrereton 14 | par: header This is a sample paragraph. 15 | see: "[Slides](https://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf) from an LLVM dev meeting chat on the comment parsing feature" 16 | warning: This is a sample warning. 17 | defined_in_file: comments.cpp 18 | declaration: "\nstruct some_struct;" 19 | ctor: unspecified 20 | fields: 21 | _x: 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - A trailing comment that documents `_x`. 26 | type: int 27 | --- 28 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/compiler_generated/m_compiler_generated.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: compiler_generated 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: fosterbrereton 11 | defined_in_file: comments.cpp 12 | is_ctor: true 13 | overloads: 14 | compiler_generated(): 15 | annotation: 16 | - deleted 17 | description: __OPTIONAL__ 18 | signature_with_names: compiler_generated() 19 | compiler_generated(const compiler_generated &): 20 | annotation: 21 | - defaulted 22 | arguments: 23 | - description: __OPTIONAL__ 24 | name: unnamed-0 25 | type: const compiler_generated & 26 | unnamed: true 27 | description: __OPTIONAL__ 28 | signature_with_names: compiler_generated(const compiler_generated &) 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/m_operator-3D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: operator-= 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - Subtraction-assignment operator. 12 | defined_in_file: point.cpp 13 | overloads: 14 | constexpr point & operator-=(const point &): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: a 18 | type: const point & 19 | description: __INLINED__ 20 | inline: 21 | arguments: 22 | a: 23 | description: The point to subtract from this point 24 | description: 25 | - Subtraction-assignment operator. 26 | return: A reference to `this`. 27 | return: __OPTIONAL__ 28 | signature_with_names: constexpr point & operator-=(const point & a) 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/f_operator3D3D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: operator== 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - Equality operator. 12 | defined_in_file: point.cpp 13 | overloads: 14 | constexpr bool operator==(const point &, const point &): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: a 18 | type: const point & 19 | - description: __OPTIONAL__ 20 | name: b 21 | type: const point & 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - Equality operator. 26 | return: "`true` iff the two points' `x` and `y` coordinates are memberwise equal." 27 | return: __OPTIONAL__ 28 | signature_with_names: constexpr bool operator==(const point & a, const point & b) 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/f_operator213D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: operator!= 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - Inequality operator. 12 | defined_in_file: point.cpp 13 | overloads: 14 | constexpr bool operator!=(const point &, const point &): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: a 18 | type: const point & 19 | - description: __OPTIONAL__ 20 | name: b 21 | type: const point & 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - Inequality operator. 26 | return: "`true` iff the two points' `x` or `y` coordinates are memberwise inequal." 27 | return: __OPTIONAL__ 28 | signature_with_names: constexpr bool operator!=(const point & a, const point & b) 29 | --- 30 | -------------------------------------------------------------------------------- /generate_test_files.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | #very simple for now, look in common locations 4 | find_hyde() { 5 | BUILD_DIR=$1 6 | if [ -f $BUILD_DIR/hyde ] 7 | then 8 | echo $BUILD_DIR/hyde 9 | return 0 10 | fi 11 | if [ -f $BUILD_DIR/Debug/hyde ] 12 | then 13 | echo $BUILD_DIR/Debug/hyde 14 | return 0 15 | fi 16 | if [ -f $BUILD_DIR/Release/hyde ] 17 | then 18 | echo $BUILD_DIR/Release/hyde 19 | return 0 20 | fi 21 | return 1 22 | } 23 | 24 | EXE_DIR=$(dirname "$0") 25 | 26 | pushd ${EXE_DIR} > /dev/null 27 | 28 | CUR_DIR=$(pwd) 29 | HYDE_PATH=`find_hyde "${CUR_DIR}/build"` 30 | 31 | for CUR_FILE in ${CUR_DIR}/test_files/*; do 32 | # echo "Processing $CUR_FILE" 33 | CUR_COMMAND="${HYDE_PATH} -hyde-update -auto-toolchain-includes -use-system-clang "$CUR_FILE" --" 34 | echo $CUR_COMMAND 35 | eval $CUR_COMMAND 36 | done 37 | 38 | popd > /dev/null 39 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_template_member_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: template_member_function 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: _multiple descriptions_ 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | overloads: 14 | "template \nvoid template_member_function()": 15 | description: __INLINED__ 16 | inline: 17 | description: 18 | - templatized member function. 19 | return: __OPTIONAL__ 20 | signature_with_names: "template \nvoid template_member_function()" 21 | void template_member_function(): 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - specialization of the above templatized member function. 26 | return: __OPTIONAL__ 27 | signature_with_names: void template_member_function() 28 | --- 29 | -------------------------------------------------------------------------------- /docs/index.html: -------------------------------------------------------------------------------- 1 | --- 2 | layout: default 3 | --- 4 | 5 |
6 | 7 | 8 | 9 | 17 | 18 |
10 | 11 |
12 |
13 |
Libraries
14 |
15 | 16 |
19 | 20 |

Posts

21 | 22 |
    23 | {% for post in site.posts %} 24 |
  • 25 | {{ post.date | date: "%b %-d, %Y" }} 26 | 27 |

    28 | {{ post.title }} 29 |

    30 | {{ post.excerpt }} 31 |
    • 32 | {% endfor %} 33 |
34 | 35 |

subscribe via RSS

36 | 37 |
38 | -------------------------------------------------------------------------------- /docs/libraries/typedef_and_alias.cpp/template_example_instantiator/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: template_example_instantiator 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: Example struct that leverages type aliases defined above. 11 | defined_in_file: typedef_and_alias.cpp 12 | declaration: "\nstruct template_example_instantiator;" 13 | ctor: unspecified 14 | dtor: unspecified 15 | typedefs: 16 | typedef_full_specialization_example: 17 | definition: using_partial_specialization_example 18 | description: __INLINED__ 19 | inline: 20 | description: 21 | - Example partial specialization using `typedef` 22 | using_full_specialization_example: 23 | definition: using_partial_specialization_example 24 | description: __INLINED__ 25 | inline: 26 | description: 27 | - Example full specialization 28 | --- 29 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | 5 | --- 6 | 7 | **Describe the bug** 8 | A clear and concise description of what the bug is. 9 | 10 | **To Reproduce** 11 | Steps to reproduce the behavior: 12 | 1. Go to '...' 13 | 2. Click on '....' 14 | 3. Scroll down to '....' 15 | 4. See error 16 | 17 | **Expected behavior** 18 | A clear and concise description of what you expected to happen. 19 | 20 | **Screenshots** 21 | If applicable, add screenshots to help explain your problem. 22 | 23 | **Desktop (please complete the following information):** 24 | - OS: [e.g. iOS] 25 | - Browser [e.g. chrome, safari] 26 | - Version [e.g. 22] 27 | 28 | **Smartphone (please complete the following information):** 29 | - Device: [e.g. iPhone6] 30 | - OS: [e.g. iOS8.1] 31 | - Browser [e.g. stock browser, safari] 32 | - Version [e.g. 22] 33 | 34 | **Additional context** 35 | Add any other context about the problem here. 36 | -------------------------------------------------------------------------------- /docs/_config.yml: -------------------------------------------------------------------------------- 1 | # Welcome to Jekyll! 2 | # 3 | # This config file is meant for settings that affect your whole blog, values 4 | # which you are expected to set up once and rarely need to edit after that. 5 | # For technical reasons, this file is *NOT* reloaded automatically when you use 6 | # 'jekyll serve'. If you change this file, please restart the server process. 7 | 8 | # Site settings 9 | title: Hyde Example Docs 10 | subtitle: Website showing a possible Jekyll-formatted hyde output. 11 | email: noreply@adobe.com 12 | baseurl: /hyde 13 | url: "https://opensource.adobe.com/" # the base hostname & protocol for your site 14 | repository: adobe/hyde 15 | remote_theme: adobe/hyde-theme@v2.0.0 16 | exclude: 17 | - "*.sh" 18 | - vendor # For Travis-CI (see https://jekyllrb.com/docs/continuous-integration/) 19 | 20 | adobe_hyde: 21 | header_image: /images/site/hyde.svg 22 | 23 | # Build settings 24 | markdown: kramdown 25 | 26 | plugins: 27 | - jekyll-redirect-from 28 | - jekyll-remote-theme 29 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/color.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: enumeration 3 | title: color 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - enumeration 9 | inline: 10 | brief: an example enumeration within the class. 11 | description: 12 | - Note that nested classes will not inherit their ownership from the class that contains them, so thus need their own `hyde-owner`. 13 | owner: sean-parent 14 | defined_in_file: classes.cpp 15 | values: 16 | - description: __INLINED__ 17 | inline: 18 | description: 19 | - this is an example description for the `red` value. 20 | name: red 21 | - description: __INLINED__ 22 | inline: 23 | description: 24 | - this is an example description for the `green` value. 25 | name: green 26 | - description: __INLINED__ 27 | inline: 28 | description: 29 | - this is an example description for the `blue` value. 30 | name: blue 31 | --- 32 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/nested_class_example/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: nested_class_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: a class definition contained within `example_class`. 11 | description: 12 | - Note that nested classes will not inherit their ownership from the class that contains them, so thus need their own `hyde-owner`. 13 | owner: sean-parent 14 | defined_in_file: classes.cpp 15 | declaration: "\nstruct class_example::nested_class_example;" 16 | ctor: unspecified 17 | dtor: unspecified 18 | fields: 19 | _x: 20 | description: __INLINED__ 21 | inline: 22 | description: 23 | - member field `_x` within the nested class example. 24 | type: int 25 | _y: 26 | description: __INLINED__ 27 | inline: 28 | description: 29 | - member field `_y` within the nested class example. 30 | type: int 31 | --- 32 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_other_struct/m_some_other_struct.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: some_other_struct 4 | hyde: 5 | owner: __OPTIONAL__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | defined_in_file: comments.cpp 10 | is_ctor: true 11 | overloads: 12 | some_other_struct(const some_other_struct &): 13 | annotation: 14 | - implicit 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: unnamed-0 18 | type: const some_other_struct & 19 | unnamed: true 20 | description: __OPTIONAL__ 21 | signature_with_names: some_other_struct(const some_other_struct &) 22 | some_other_struct(some_other_struct &&): 23 | annotation: 24 | - implicit 25 | arguments: 26 | - description: __OPTIONAL__ 27 | name: unnamed-0 28 | type: some_other_struct && 29 | unnamed: true 30 | description: __OPTIONAL__ 31 | signature_with_names: some_other_struct(some_other_struct &&) 32 | --- 33 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_binary_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: binary_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - an example binary function. 12 | defined_in_file: functions.cpp 13 | overloads: 14 | int binary_function_example(int, int): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: first 18 | type: int 19 | - description: __OPTIONAL__ 20 | name: second 21 | type: int 22 | description: __INLINED__ 23 | inline: 24 | arguments: 25 | first: 26 | description: the first input 27 | second: 28 | description: the second input 29 | description: 30 | - an example binary function. 31 | return: The sum of the two input parameters. 32 | return: __OPTIONAL__ 33 | signature_with_names: int binary_function_example(int first, int second) 34 | --- 35 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_template_function_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: template_function_example 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: _multiple descriptions_ 11 | defined_in_file: functions.cpp 12 | overloads: 13 | int template_function_example(): 14 | description: __INLINED__ 15 | inline: 16 | description: 17 | - an example specialization of the template function example 18 | return: Forty-two 19 | return: __OPTIONAL__ 20 | signature_with_names: int template_function_example() 21 | "template \nT template_function_example()": 22 | description: __INLINED__ 23 | inline: 24 | description: 25 | - an example template function, deleted by default 26 | return: Not applicable, seeing that the default definition has been deleted. 27 | return: __OPTIONAL__ 28 | signature_with_names: "template \nT template_function_example()" 29 | --- 30 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_class_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: class_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: _multiple descriptions_ 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | is_ctor: true 14 | overloads: 15 | class_example(): 16 | annotation: 17 | - defaulted 18 | description: __INLINED__ 19 | inline: 20 | description: 21 | - default constructor. 22 | signature_with_names: class_example() 23 | explicit class_example(int): 24 | arguments: 25 | - description: __OPTIONAL__ 26 | name: x 27 | type: int 28 | description: __INLINED__ 29 | inline: 30 | arguments: 31 | x: 32 | description: The one integer parameter this routine takes 33 | description: 34 | - an explicit constructor that takes a single `int`. 35 | signature_with_names: explicit class_example(int x) 36 | --- 37 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_deprecated.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: deprecated 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - deprecated member function. 12 | owner: fosterbrereton 13 | defined_in_file: classes.cpp 14 | overloads: 15 | void deprecated(const std::string &, class_example *): 16 | annotation: 17 | - deprecated 18 | arguments: 19 | - description: __OPTIONAL__ 20 | name: first 21 | type: const std::string & 22 | - description: __OPTIONAL__ 23 | name: second 24 | type: class_example * 25 | description: __INLINED__ 26 | inline: 27 | arguments: 28 | first: 29 | description: the first parameter 30 | second: 31 | description: the second parameter 32 | description: 33 | - deprecated member function. 34 | return: __OPTIONAL__ 35 | signature_with_names: void deprecated(const std::string & first, class_example * second) 36 | --- 37 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_other_struct/m_operator3D.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: operator= 4 | hyde: 5 | owner: __OPTIONAL__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | defined_in_file: comments.cpp 10 | overloads: 11 | some_other_struct & operator=(const some_other_struct &): 12 | annotation: 13 | - implicit 14 | arguments: 15 | - description: __OPTIONAL__ 16 | name: unnamed-0 17 | type: const some_other_struct & 18 | unnamed: true 19 | description: __OPTIONAL__ 20 | return: __OPTIONAL__ 21 | signature_with_names: some_other_struct & operator=(const some_other_struct &) 22 | some_other_struct & operator=(some_other_struct &&): 23 | annotation: 24 | - implicit 25 | arguments: 26 | - description: __OPTIONAL__ 27 | name: unnamed-0 28 | type: some_other_struct && 29 | unnamed: true 30 | description: __OPTIONAL__ 31 | return: __OPTIONAL__ 32 | signature_with_names: some_other_struct & operator=(some_other_struct &&) 33 | --- 34 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/f_operator-.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: operator- 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: 11 | - Subtraction operator. 12 | defined_in_file: point.cpp 13 | overloads: 14 | constexpr point operator-(const point &, const point &): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: a 18 | type: const point & 19 | - description: __OPTIONAL__ 20 | name: b 21 | type: const point & 22 | description: __INLINED__ 23 | inline: 24 | arguments: 25 | a: 26 | description: The point to be subtracted from. 27 | b: 28 | description: The point to subtract. 29 | description: 30 | - Subtraction operator. 31 | return: A new point whose axis values are subtractions of the two inputs' axis values. 32 | return: __OPTIONAL__ 33 | signature_with_names: constexpr point operator-(const point & a, const point & b) 34 | --- 35 | -------------------------------------------------------------------------------- /include/json_fwd.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | 17 | // nlohmann/json 18 | #include "nlohmann/json_fwd.hpp" 19 | 20 | /**************************************************************************************************/ 21 | 22 | namespace hyde { 23 | 24 | /**************************************************************************************************/ 25 | 26 | using json = nlohmann::json; 27 | 28 | using optional_json = std::optional; 29 | 30 | /**************************************************************************************************/ 31 | 32 | } // namespace hyde 33 | 34 | /**************************************************************************************************/ 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | © Copyright 2018 Adobe. All rights reserved. 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /docs/libraries/point.cpp/point3CT3E/m_point3CT3E.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: point 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: _multiple descriptions_ 11 | defined_in_file: point.cpp 12 | is_ctor: true 13 | overloads: 14 | point(): 15 | annotation: 16 | - defaulted 17 | description: __INLINED__ 18 | inline: 19 | description: 20 | - Default constructor of default definition. 21 | signature_with_names: point() 22 | point(T, T): 23 | arguments: 24 | - description: __OPTIONAL__ 25 | name: _x 26 | type: T 27 | - description: __OPTIONAL__ 28 | name: _y 29 | type: T 30 | description: __INLINED__ 31 | inline: 32 | arguments: 33 | _x: 34 | description: The `x` coordinate to sink. 35 | _y: 36 | description: The `y` coordinate to sink. 37 | description: 38 | - Value-based constructor that takes `x` and `y` values and sinks them into place. 39 | signature_with_names: point(T _x, T _y) 40 | --- 41 | -------------------------------------------------------------------------------- /include/config.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | /**************************************************************************************************/ 15 | 16 | #define HYDE_PRIVATE_STRING_XSMASH(X, Y) X##Y 17 | #define HYDE_PRIVATE_STRING_SMASH(X, Y) HYDE_PRIVATE_STRING_XSMASH(X, Y)() 18 | 19 | #define HYDE_PLATFORM_PRIVATE_APPLE() 0 20 | #define HYDE_PLATFORM_PRIVATE_MICROSOFT() 0 21 | 22 | #define HYDE_PLATFORM(X) HYDE_PRIVATE_STRING_SMASH(HYDE_PLATFORM_PRIVATE_, X) 23 | 24 | #if defined(__APPLE__) 25 | #undef HYDE_PLATFORM_PRIVATE_APPLE 26 | #define HYDE_PLATFORM_PRIVATE_APPLE() 1 27 | #elif defined(_MSC_VER) 28 | #undef HYDE_PLATFORM_PRIVATE_MICROSOFT 29 | #define HYDE_PLATFORM_PRIVATE_MICROSOFT() 1 30 | #endif 31 | 32 | /**************************************************************************************************/ 33 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_deprecated_with_message.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: deprecated_with_message 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: 11 | - deprecated member function that contains a compile-time deprecation message. 12 | owner: fosterbrereton 13 | defined_in_file: classes.cpp 14 | overloads: 15 | void deprecated_with_message(const std::string &, class_example *): 16 | annotation: 17 | - deprecated("example deprecation message") 18 | arguments: 19 | - description: __OPTIONAL__ 20 | name: s 21 | type: const std::string & 22 | - description: __OPTIONAL__ 23 | name: f 24 | type: class_example * 25 | description: __INLINED__ 26 | inline: 27 | arguments: 28 | f: 29 | description: the second parameter 30 | s: 31 | description: the first parameter 32 | description: 33 | - deprecated member function that contains a compile-time deprecation message. 34 | return: __OPTIONAL__ 35 | signature_with_names: void deprecated_with_message(const std::string & s, class_example * f) 36 | --- 37 | -------------------------------------------------------------------------------- /include/autodetect.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | #include 17 | #include 18 | 19 | // application 20 | #include "config.hpp" 21 | 22 | /**************************************************************************************************/ 23 | 24 | namespace hyde { 25 | 26 | /**************************************************************************************************/ 27 | 28 | std::vector autodetect_toolchain_paths(); 29 | 30 | std::filesystem::path autodetect_resource_directory(); 31 | 32 | #if HYDE_PLATFORM(APPLE) 33 | std::filesystem::path autodetect_sysroot_directory(); 34 | #endif // HYDE_PLATFORM(APPLE) 35 | 36 | /**************************************************************************************************/ 37 | 38 | } // namespace hyde 39 | 40 | /**************************************************************************************************/ 41 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/nested_class_example/m_nested_class_example.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: nested_class_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __OPTIONAL__ 7 | tags: 8 | - method 9 | inline: 10 | owner: sean-parent 11 | defined_in_file: classes.cpp 12 | is_ctor: true 13 | overloads: 14 | nested_class_example(): 15 | annotation: 16 | - implicit 17 | description: __OPTIONAL__ 18 | signature_with_names: nested_class_example() 19 | nested_class_example(class_example::nested_class_example &&): 20 | annotation: 21 | - implicit 22 | arguments: 23 | - description: __OPTIONAL__ 24 | name: unnamed-0 25 | type: class_example::nested_class_example && 26 | unnamed: true 27 | description: __OPTIONAL__ 28 | signature_with_names: nested_class_example(class_example::nested_class_example &&) 29 | nested_class_example(const class_example::nested_class_example &): 30 | annotation: 31 | - implicit 32 | arguments: 33 | - description: __OPTIONAL__ 34 | name: unnamed-0 35 | type: const class_example::nested_class_example & 36 | unnamed: true 37 | description: __OPTIONAL__ 38 | signature_with_names: nested_class_example(const class_example::nested_class_example &) 39 | --- 40 | -------------------------------------------------------------------------------- /docs/feed.xml: -------------------------------------------------------------------------------- 1 | --- 2 | layout: null 3 | --- 4 | 5 | 6 | 7 | {{ site.title | xml_escape }} 8 | {{ site.description | xml_escape }} 9 | {{ site.url }}{{ site.baseurl }}/ 10 | 11 | {{ site.time | date_to_rfc822 }} 12 | {{ site.time | date_to_rfc822 }} 13 | Jekyll v{{ jekyll.version }} 14 | {% for post in site.posts limit:10 %} 15 | 16 | {{ post.title | xml_escape }} 17 | {{ post.content | xml_escape }} 18 | {{ post.date | date_to_rfc822 }} 19 | {{ post.url | prepend: site.baseurl | prepend: site.url }} 20 | {{ post.url | prepend: site.baseurl | prepend: site.url }} 21 | {% for tag in post.tags %} 22 | {{ tag | xml_escape }} 23 | {% endfor %} 24 | {% for cat in post.categories %} 25 | {{ cat | xml_escape }} 26 | {% endfor %} 27 | 28 | {% endfor %} 29 | 30 | 31 | -------------------------------------------------------------------------------- /docs/_includes/head.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | {% if page.title %}{{ page.title }}{% else %}{{ site.title }}{% endif %} 7 | 8 | 11 | 12 | 13 | 14 | 15 | 20 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /docs/libraries/typedef_and_alias.cpp/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: library 3 | title: typedef_and_alias.cpp 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __MISSING__ 7 | tags: 8 | - sourcefile 9 | library-type: sourcefile 10 | typedefs: 11 | typedef_example: 12 | definition: int 13 | description: __INLINED__ 14 | inline: 15 | description: 16 | - Example typedef expression whose underlying type is `int`. 17 | typedef_full_specialization_example: 18 | definition: using_partial_specialization_example 19 | description: __INLINED__ 20 | inline: 21 | description: 22 | - Using typedef to define another full specialization of the above partial specialization 23 | using_example: 24 | definition: int 25 | description: __INLINED__ 26 | inline: 27 | description: 28 | - Example using expression whose underlying type is `int`. 29 | using_full_specialization_example: 30 | definition: using_partial_specialization_example 31 | description: __INLINED__ 32 | inline: 33 | description: 34 | - Full specialization of the above partial specialization 35 | using_partial_specialization_example: 36 | definition: template_example 37 | description: __INLINED__ 38 | inline: 39 | description: 40 | - Partial specialization of the above `template_example` template 41 | --- 42 | -------------------------------------------------------------------------------- /matchers/matcher_fwd.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | #include 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | enum ToolAccessFilter { 25 | ToolAccessFilterPrivate, 26 | ToolAccessFilterProtected, 27 | ToolAccessFilterPublic, 28 | }; 29 | 30 | /**************************************************************************************************/ 31 | 32 | struct processing_options { 33 | std::vector _paths; 34 | ToolAccessFilter _access_filter; 35 | std::vector _namespace_blacklist; 36 | bool _process_class_methods; 37 | }; 38 | 39 | /**************************************************************************************************/ 40 | 41 | } // namespace hyde 42 | 43 | /**************************************************************************************************/ 44 | -------------------------------------------------------------------------------- /test_files/enums.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // AST dump with 13 | // clang --std=c++1z -Xclang -ast-dump -fsyntax-only ./enums.cpp 14 | 15 | //------------------------------------------------------------------------------------------------------------------------------------------ 16 | 17 | /// @brief An example typed enumeration with three values. 18 | /// @hyde-owner fosterbrereton 19 | enum class color_channel { 20 | /// Red commentary 21 | red, 22 | /// Green commentary. Note this enum has a pre-set value. 23 | green = 42, 24 | /// Blue commentary 25 | blue, 26 | }; 27 | 28 | //------------------------------------------------------------------------------------------------------------------------------------------ 29 | 30 | /// @brief An example untyped enumeration with three values. 31 | /// @hyde-owner fosterbrereton 32 | enum untyped { 33 | /// Apple commentary 34 | apple, 35 | /// Orange commentary 36 | orange, 37 | /// Banana commentary 38 | banana, 39 | }; 40 | 41 | //------------------------------------------------------------------------------------------------------------------------------------------ 42 | -------------------------------------------------------------------------------- /emitters/yaml_enum_emitter.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // application 15 | #include "emitters/yaml_base_emitter.hpp" 16 | #include "json.hpp" 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | struct yaml_enum_emitter : public yaml_base_emitter { 25 | explicit yaml_enum_emitter(std::filesystem::path src_root, 26 | std::filesystem::path dst_root, 27 | yaml_mode mode, 28 | emit_options options) 29 | : yaml_base_emitter(std::move(src_root), std::move(dst_root), mode, std::move(options)) {} 30 | 31 | bool emit(const json& matched, json& output, const json& inherited) override; 32 | 33 | bool do_merge(const std::string& filepath, 34 | const json& have, 35 | const json& expected, 36 | json& out_merged) override; 37 | }; 38 | 39 | /**************************************************************************************************/ 40 | 41 | } // namespace hyde 42 | 43 | /**************************************************************************************************/ 44 | -------------------------------------------------------------------------------- /emitters/yaml_class_emitter.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // application 15 | #include "emitters/yaml_base_emitter.hpp" 16 | #include "json.hpp" 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | struct yaml_class_emitter : public yaml_base_emitter { 25 | explicit yaml_class_emitter(std::filesystem::path src_root, 26 | std::filesystem::path dst_root, 27 | yaml_mode mode, 28 | emit_options options) 29 | : yaml_base_emitter(std::move(src_root), std::move(dst_root), mode, std::move(options)) {} 30 | 31 | bool emit(const json& matched, json& output, const json& inherited) override; 32 | 33 | bool do_merge(const std::string& filepath, 34 | const json& have, 35 | const json& expected, 36 | json& out_merged) override; 37 | }; 38 | 39 | /**************************************************************************************************/ 40 | 41 | } // namespace hyde 42 | 43 | /**************************************************************************************************/ 44 | -------------------------------------------------------------------------------- /test_files/namespaces.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | //------------------------------------------------------------------------------------------------------------------------------------------ 13 | 14 | namespace foo { 15 | 16 | //------------------------------------------------------------------------------------------------------------------------------------------ 17 | 18 | namespace bar::baz { 19 | 20 | //------------------------------------------------------------------------------------------------------------------------------------------ 21 | 22 | /// function contained within namespaces `foo::bar::baz`. 23 | void function(); 24 | 25 | //------------------------------------------------------------------------------------------------------------------------------------------ 26 | 27 | } // namespace bar::baz 28 | 29 | //------------------------------------------------------------------------------------------------------------------------------------------ 30 | 31 | /// function contained within namespace `foo`. 32 | void function(); 33 | 34 | //------------------------------------------------------------------------------------------------------------------------------------------ 35 | 36 | } // namespace foo 37 | 38 | //------------------------------------------------------------------------------------------------------------------------------------------ 39 | -------------------------------------------------------------------------------- /emitters/yaml_library_emitter.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // application 15 | #include "emitters/yaml_base_emitter.hpp" 16 | #include "json.hpp" 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | struct yaml_library_emitter : public yaml_base_emitter { 25 | explicit yaml_library_emitter(std::filesystem::path src_root, 26 | std::filesystem::path dst_root, 27 | yaml_mode mode, 28 | emit_options options) 29 | : yaml_base_emitter( 30 | std::move(src_root), std::move(dst_root), mode, std::move(options), true) {} 31 | 32 | bool emit(const json& matched, json& output, const json& inherited) override; 33 | 34 | bool do_merge(const std::string& filepath, 35 | const json& have, 36 | const json& expected, 37 | json& out_merged) override; 38 | }; 39 | 40 | /**************************************************************************************************/ 41 | 42 | } // namespace hyde 43 | 44 | /**************************************************************************************************/ 45 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: class 3 | title: class_example 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - class 9 | inline: 10 | brief: an example class that demonstrates what Hyde documents. 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | declaration: "\nclass class_example;" 14 | dtor: unspecified 15 | typedefs: 16 | typedef_example: 17 | definition: std::string 18 | description: __INLINED__ 19 | inline: 20 | description: 21 | - a nested `typedef` expression. 22 | using_example: 23 | definition: std::string 24 | description: __INLINED__ 25 | inline: 26 | description: 27 | - a nested `using` expression. 28 | fields: 29 | _deprecated_member: 30 | annotation: 31 | - private 32 | - deprecated("example deprecation message") 33 | description: __INLINED__ 34 | inline: 35 | description: 36 | - a deprecated member variable that contains a message. Apparently this works?! 37 | type: int 38 | _nested: 39 | annotation: 40 | - private 41 | description: __INLINED__ 42 | inline: 43 | description: 44 | - an instance of the nested class example defined earlier. 45 | type: class_example::nested_class_example 46 | _static_member: 47 | description: __INLINED__ 48 | inline: 49 | description: 50 | - static member variable. 51 | type: const int 52 | _x: 53 | annotation: 54 | - private 55 | description: __INLINED__ 56 | inline: 57 | description: 58 | - some variable that holds an integer. 59 | type: int 60 | --- 61 | -------------------------------------------------------------------------------- /include/output_yaml.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | 17 | // application 18 | #include "json_fwd.hpp" 19 | #include "emitters/yaml_base_emitter_fwd.hpp" 20 | 21 | /**************************************************************************************************/ 22 | 23 | namespace hyde { 24 | 25 | /**************************************************************************************************/ 26 | 27 | enum class yaml_mode { 28 | validate, // ensure the destination docs match the shape of the generated docs 29 | update, // update the destination docs to match the shape of the generated docs 30 | transcribe // transcribe the destination docs to match the symbols put out by upgraded tooling 31 | }; 32 | 33 | /**************************************************************************************************/ 34 | 35 | void output_yaml(json j, 36 | const std::filesystem::path& src_root, 37 | const std::filesystem::path& dst_root, 38 | json& out_emitted, 39 | yaml_mode mode, 40 | const emit_options& options); 41 | 42 | /**************************************************************************************************/ 43 | 44 | } // namespace hyde 45 | 46 | /**************************************************************************************************/ 47 | -------------------------------------------------------------------------------- /docs/libraries/comments.cpp/some_struct/m_some_function.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: some_function 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: A function that does a thing, and does it well. 11 | owner: fosterbrereton 12 | defined_in_file: comments.cpp 13 | overloads: 14 | int some_function(int, int &, int &): 15 | arguments: 16 | - description: __OPTIONAL__ 17 | name: input 18 | type: int 19 | - description: __OPTIONAL__ 20 | name: input_output 21 | type: int & 22 | - description: __OPTIONAL__ 23 | name: output 24 | type: int & 25 | description: __INLINED__ 26 | inline: 27 | arguments: 28 | input: 29 | description: an input parameter 30 | direction: in 31 | input_output: 32 | description: a bidirectional parameter 33 | direction: inout 34 | output: 35 | description: an output parameter 36 | direction: out 37 | brief: A function that does a thing, and does it well. 38 | description: 39 | - This is a longer description of this function that does things as well as it does. Notice how long this comment is! So impressive. 💥 40 | post: An example postcondition. 41 | pre: An example precondition. 42 | return: Some additional value. 43 | throw: "`std::runtime_error` if the function actually _can't_ do the thing. Sorry!" 44 | todo: This really could use some cleanup. Although, its implementation doesn't exist... 45 | warning: This function may be very expensive to run. Do not call it inside a loop. 46 | return: __OPTIONAL__ 47 | signature_with_names: int some_function(int input, int & input_output, int & output) 48 | --- 49 | -------------------------------------------------------------------------------- /matchers/namespace_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "namespace_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 25 | // clang-format on 26 | 27 | // application 28 | #include "json.hpp" 29 | #include "matchers/utilities.hpp" 30 | 31 | using namespace clang; 32 | using namespace clang::ast_matchers; 33 | 34 | /**************************************************************************************************/ 35 | 36 | namespace hyde { 37 | 38 | /**************************************************************************************************/ 39 | 40 | void NamespaceInfo::run(const MatchFinder::MatchResult& Result) { 41 | auto ns = Result.Nodes.getNodeAs("ns"); 42 | auto info_opt = StandardDeclInfo(_options, ns); 43 | if (!info_opt) return; 44 | auto info = std::move(*info_opt); 45 | 46 | _j["namespaces"].push_back(std::move(info)); 47 | } 48 | 49 | /**************************************************************************************************/ 50 | 51 | } // namespace hyde 52 | 53 | /**************************************************************************************************/ 54 | -------------------------------------------------------------------------------- /matchers/enum_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class EnumInfo : public MatchFinder::MatchCallback { 36 | public: 37 | EnumInfo(processing_options options) : _options(std::move(options)) { 38 | _j["enums"] = json::array(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return enumDecl().bind("enum"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /matchers/class_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class ClassInfo : public MatchFinder::MatchCallback { 36 | public: 37 | explicit ClassInfo(processing_options options) : _options(std::move(options)) { 38 | _j["class"] = json::array(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return cxxRecordDecl().bind("class"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /matchers/function_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class FunctionInfo : public MatchFinder::MatchCallback { 36 | public: 37 | FunctionInfo(processing_options options) : _options(std::move(options)) { 38 | _j["functions"] = json::object(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return functionDecl().bind("func"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /matchers/typedef_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class TypedefInfo : public MatchFinder::MatchCallback { 36 | public: 37 | TypedefInfo(processing_options options) : _options(std::move(options)) { 38 | _j["typedefs"] = json::array(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return typedefDecl().bind("typedef"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /matchers/namespace_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class NamespaceInfo : public MatchFinder::MatchCallback { 36 | public: 37 | NamespaceInfo(processing_options options) : _options(std::move(options)) { 38 | _j["namespaces"] = json::array(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return namespaceDecl().bind("ns"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /matchers/typealias_matcher.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // clang/llvm 15 | // clang-format off 16 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 17 | #include "clang/ASTMatchers/ASTMatchFinder.h" 18 | #include "clang/ASTMatchers/ASTMatchers.h" 19 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 20 | // clang-format on 21 | 22 | // application 23 | #include "json.hpp" 24 | #include "matchers/matcher_fwd.hpp" 25 | 26 | using namespace clang; 27 | using namespace clang::ast_matchers; 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | class TypeAliasInfo : public MatchFinder::MatchCallback { 36 | public: 37 | TypeAliasInfo(processing_options options) : _options(std::move(options)) { 38 | _j["typealiases"] = json::array(); 39 | } 40 | 41 | void run(const MatchFinder::MatchResult& Result) override; 42 | 43 | json getJSON() { return _j; } 44 | 45 | static DeclarationMatcher GetMatcher() { return typeAliasDecl().bind("typealias"); } 46 | 47 | private: 48 | processing_options _options; 49 | json _j; 50 | }; 51 | 52 | /**************************************************************************************************/ 53 | 54 | } // namespace hyde 55 | 56 | /**************************************************************************************************/ 57 | -------------------------------------------------------------------------------- /emitters/yaml_function_emitter.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // application 15 | #include "emitters/yaml_base_emitter.hpp" 16 | #include "json.hpp" 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | struct yaml_function_emitter : public yaml_base_emitter { 25 | explicit yaml_function_emitter(std::filesystem::path src_root, 26 | std::filesystem::path dst_root, 27 | yaml_mode mode, 28 | emit_options options, 29 | bool as_methods) 30 | : yaml_base_emitter(std::move(src_root), std::move(dst_root), mode, std::move(options)), 31 | _as_methods(as_methods) {} 32 | 33 | void set_key(std::string key) { _key = std::move(key); } 34 | 35 | bool emit(const json& matched, json& output, const json& inherited) override; 36 | 37 | bool do_merge(const std::string& filepath, 38 | const json& have, 39 | const json& expected, 40 | json& out_merged) override; 41 | 42 | private: 43 | std::string _key; 44 | bool _as_methods; 45 | }; 46 | 47 | /**************************************************************************************************/ 48 | 49 | } // namespace hyde 50 | 51 | /**************************************************************************************************/ 52 | -------------------------------------------------------------------------------- /emitters/yaml_sourcefile_emitter.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // application 15 | #include "emitters/yaml_base_emitter.hpp" 16 | #include "json.hpp" 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | struct yaml_sourcefile_emitter : public yaml_base_emitter { 25 | explicit yaml_sourcefile_emitter(std::filesystem::path src_root, 26 | std::filesystem::path dst_root, 27 | yaml_mode mode, 28 | emit_options options) 29 | : yaml_base_emitter(std::move(src_root), std::move(dst_root), mode, std::move(options)) {} 30 | 31 | bool emit(const json& matched, json& output, const json& inherited) override; 32 | 33 | bool do_merge(const std::string& filepath, 34 | const json& have, 35 | const json& expected, 36 | json& out_merged) override; 37 | 38 | bool extraneous_file_check(); 39 | 40 | private: 41 | bool extraneous_file_check_internal(const std::filesystem::path& root, 42 | const std::filesystem::path& path); 43 | 44 | std::filesystem::path _sub_dst; 45 | }; 46 | 47 | /**************************************************************************************************/ 48 | 49 | } // namespace hyde 50 | 51 | /**************************************************************************************************/ 52 | -------------------------------------------------------------------------------- /matchers/typedef_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "typedef_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 25 | // clang-format on 26 | 27 | // application 28 | #include "json.hpp" 29 | #include "matchers/utilities.hpp" 30 | 31 | using namespace clang; 32 | using namespace clang::ast_matchers; 33 | 34 | /**************************************************************************************************/ 35 | 36 | namespace hyde { 37 | 38 | /**************************************************************************************************/ 39 | 40 | void TypedefInfo::run(const MatchFinder::MatchResult& Result) { 41 | auto node = Result.Nodes.getNodeAs("typedef"); 42 | auto info_opt = StandardDeclInfo(_options, node); 43 | if (!info_opt) return; 44 | auto info = std::move(*info_opt); 45 | 46 | // do not process class type aliases here. 47 | if (!info["parents"].empty()) return; 48 | 49 | info["type"] = hyde::to_string(node, node->getUnderlyingType()); 50 | 51 | _j["typedefs"].push_back(std::move(info)); 52 | } 53 | 54 | /**************************************************************************************************/ 55 | 56 | } // namespace hyde 57 | 58 | /**************************************************************************************************/ 59 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Thanks for choosing to contribute! 4 | 5 | The following are a set of guidelines to follow when contributing to this project. 6 | 7 | ## Code Of Conduct 8 | 9 | This project adheres to the Adobe [code of conduct](CODE_OF_CONDUCT.md). By participating, 10 | you are expected to uphold this code. Please report unacceptable behavior to 11 | [Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com). 12 | 13 | ## Have A Question? 14 | 15 | Start by filing an issue. The existing committers on this project work to reach 16 | consensus around project direction and issue solutions within issue threads 17 | (when appropriate). 18 | 19 | ## Contributor License Agreement 20 | 21 | All third-party contributions to this project must be accompanied by a signed contributor 22 | license agreement. This gives Adobe permission to redistribute your contributions 23 | as part of the project. [Sign our CLA](http://opensource.adobe.com/cla.html). You 24 | only need to submit an Adobe CLA one time, so if you have submitted one previously, 25 | you are good to go! 26 | 27 | ## Code Reviews 28 | 29 | All submissions should come in the form of pull requests and need to be reviewed 30 | by project committers. Read [GitHub's pull request documentation](https://help.github.com/articles/about-pull-requests/) 31 | for more information on sending pull requests. 32 | 33 | ## From Contributor To Committer 34 | 35 | We love contributions from our community! If you'd like to go a step beyond contributor 36 | and become a committer with full write access and a say in the project, you must 37 | be invited to the project. The existing committers employ an internal nomination 38 | process that must reach lazy consensus (silence is approval) before invitations 39 | are issued. If you feel you are qualified and want to get more deeply involved, 40 | feel free to reach out to existing committers to have a conversation about that. 41 | 42 | ## Security Issues 43 | 44 | Security issues shouldn't be reported on this issue tracker. Instead, [file an issue to our security experts](https://helpx.adobe.com/security/alertus.html) 45 | -------------------------------------------------------------------------------- /.github/workflows/tagged-release.yml: -------------------------------------------------------------------------------- 1 | name: Tagged Release 2 | on: 3 | push: 4 | tags: 5 | - "v*.*.*" 6 | workflow_dispatch: null 7 | permissions: 8 | contents: write 9 | jobs: 10 | release-mac: 11 | runs-on: macos-latest 12 | steps: 13 | - name: ⬇️ Checkout sources 14 | uses: actions/checkout@v3 15 | - name: 🏗️ Setup project files 16 | run: | 17 | git submodule update --init 18 | mkdir build 19 | cd build 20 | cmake -GXcode .. 21 | - name: 🛠️ Build Hyde 22 | run: | 23 | cd build 24 | xcodebuild -quiet -target hyde -configuration Release 25 | - name: 🗜️ Create archive 26 | run: | 27 | cd build/Release 28 | # "No such xattr: com.apple.quarantine" 29 | # xattr -d com.apple.quarantine hyde 30 | strip hyde 31 | codesign --force -s - hyde 32 | tar -zcvf hyde-${{github.ref_name}}-macos.tgz hyde 33 | - name: ✍️ Post archive 34 | uses: softprops/action-gh-release@v1 35 | with: 36 | generate_release_notes: true 37 | files: 38 | build/Release/hyde-${{github.ref_name}}-macos.tgz 39 | release-linux: 40 | runs-on: ubuntu-latest 41 | steps: 42 | - name: ⬇️ Checkout sources 43 | uses: actions/checkout@v3 44 | - name: 🏗️ Set up Clang 45 | uses: egor-tensin/setup-clang@v1 46 | with: 47 | version: 18 48 | - name: 🏗️ Setup project files 49 | run: | 50 | sudo apt-get install ninja-build 51 | git submodule update --init 52 | mkdir build 53 | cd build 54 | cmake -DCMAKE_BUILD_TYPE=Release -GNinja .. 55 | - name: 🛠️ Build Hyde 56 | run: | 57 | cd build 58 | ninja 59 | - name: 🗜️ Create archive 60 | run: | 61 | cd build 62 | tar -zcvf hyde-${{github.ref_name}}-linux-${{runner.arch}}.tgz hyde 63 | - name: ✍️ Post archive 64 | uses: softprops/action-gh-release@v1 65 | with: 66 | generate_release_notes: true 67 | files: 68 | build/hyde-${{github.ref_name}}-linux-${{runner.arch}}.tgz 69 | -------------------------------------------------------------------------------- /matchers/typealias_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "typealias_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 25 | // clang-format on 26 | 27 | // application 28 | #include "json.hpp" 29 | #include "matchers/utilities.hpp" 30 | 31 | using namespace clang; 32 | using namespace clang::ast_matchers; 33 | 34 | /**************************************************************************************************/ 35 | 36 | namespace hyde { 37 | 38 | /**************************************************************************************************/ 39 | 40 | void TypeAliasInfo::run(const MatchFinder::MatchResult& Result) { 41 | auto node = Result.Nodes.getNodeAs("typealias"); 42 | 43 | auto info_opt = StandardDeclInfo(_options, node); 44 | if (!info_opt) return; 45 | auto info = std::move(*info_opt); 46 | 47 | // do not process class type aliases here. 48 | if (!info["parents"].empty()) return; 49 | 50 | info["type"] = hyde::to_string(node, node->getUnderlyingType()); 51 | 52 | if (auto template_decl = node->getDescribedAliasTemplate()) { 53 | info["template_parameters"] = GetTemplateParameters(Result.Context, template_decl); 54 | } 55 | 56 | _j["typealiases"].push_back(std::move(info)); 57 | } 58 | 59 | /**************************************************************************************************/ 60 | 61 | } // namespace hyde 62 | 63 | /**************************************************************************************************/ 64 | -------------------------------------------------------------------------------- /matchers/function_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "function_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "clang/Lex/Lexer.h" 25 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 26 | // clang-format on 27 | 28 | // application 29 | #include "json.hpp" 30 | #include "matchers/utilities.hpp" 31 | 32 | using namespace clang; 33 | using namespace clang::ast_matchers; 34 | 35 | /**************************************************************************************************/ 36 | 37 | namespace hyde { 38 | 39 | /**************************************************************************************************/ 40 | 41 | void FunctionInfo::run(const MatchFinder::MatchResult& Result) { 42 | auto function = Result.Nodes.getNodeAs("func"); 43 | 44 | // Do not process class methods here. 45 | if (!_options._process_class_methods) { 46 | if (llvm::dyn_cast_or_null(function)) return; 47 | } 48 | 49 | auto info_opt = DetailFunctionDecl(_options, function); 50 | if (!info_opt) return; 51 | auto info = std::move(*info_opt); 52 | 53 | const std::string& short_name(info["short_name"]); 54 | 55 | // Omit compiler-reserved functions 56 | if (short_name.find("__") == 0) return; 57 | 58 | _j["functions"][short_name].push_back(std::move(info)); 59 | } 60 | 61 | /**************************************************************************************************/ 62 | 63 | } // namespace hyde 64 | 65 | /**************************************************************************************************/ 66 | -------------------------------------------------------------------------------- /emitters/yaml_library_emitter.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "yaml_library_emitter.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | bool yaml_library_emitter::do_merge(const std::string& filepath, 25 | const json& have, 26 | const json& expected, 27 | json& out_merged) { 28 | bool failure{false}; 29 | 30 | failure |= check_scalar(filepath, have, expected, "", out_merged, "library-type"); 31 | failure |= check_editable_scalar(filepath, have, expected, "", out_merged, "icon"); 32 | failure |= check_editable_scalar(filepath, have, expected, "", out_merged, "tab"); 33 | failure |= check_editable_scalar(filepath, have, expected, "", out_merged, "short_title"); 34 | 35 | return failure; 36 | } 37 | 38 | /**************************************************************************************************/ 39 | 40 | bool yaml_library_emitter::emit(const json& j, json& out_emitted, const json&) { 41 | json node = 42 | base_emitter_node("library", tag_value_missing_k, "library", has_json_flag(j, "implicit")); 43 | node["hyde"]["library-type"] = "library"; 44 | node["hyde"]["icon"] = tag_value_missing_k; 45 | node["hyde"]["tab"] = tag_value_missing_k; 46 | node["hyde"]["short_title"] = tag_value_optional_k; 47 | 48 | return reconcile(std::move(node), _dst_root, _dst_root / index_filename_k, out_emitted); 49 | } 50 | 51 | /**************************************************************************************************/ 52 | 53 | } // namespace hyde 54 | 55 | /**************************************************************************************************/ 56 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | 2 | FROM --platform=linux/x86_64 ubuntu:latest 3 | RUN apt-get -y update && apt-get install -y 4 | 5 | RUN apt-get -y install curl gnupg2 software-properties-common ninja-build apt-utils make 6 | 7 | RUN apt-get -y install wget 8 | 9 | RUN apt-get -y install git 10 | 11 | # Are the build-essential packages needed? This elminates a CMake error 12 | # about /usr/bin/c++ not being found but seems like overkill. 13 | RUN apt-get -y install build-essential 14 | 15 | # Install llvm/clang 16 | 17 | # This is nesessary because of an issue with the hyde resource-dir. The 18 | # version of clang installed must exactly match the version of clang used 19 | # to build hyde. This is a temporary fix until hyde installs the necessary 20 | # resource directory and encodes the path in the binary. 21 | 22 | # If you get an error message about stddef.h or size_t not being found, 23 | # the issue is here. Check where hyde is looking for it's resoruce 24 | # directory with 25 | # `hyde ./test.hpp -- -x c++ -print-resource-dir` 26 | 27 | # FROM base AS full 28 | 29 | ENV LLVM_VERSION=15 30 | 31 | RUN apt-get -y install clang-${LLVM_VERSION} 32 | RUN apt-get -y install libc++-${LLVM_VERSION}-dev 33 | 34 | # set clang ${LLVM_VERSION} to be the version of clang we use when clang/clang++ is invoked 35 | RUN update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-${LLVM_VERSION} 100 36 | RUN update-alternatives --install /usr/bin/clang clang /usr/bin/clang-${LLVM_VERSION} 100 37 | 38 | ADD https://cmake.org/files/v3.24/cmake-3.24.0-linux-x86_64.sh /cmake-3.24.0-linux-x86_64.sh 39 | RUN mkdir /opt/cmake 40 | RUN sh /cmake-3.24.0-linux-x86_64.sh --prefix=/opt/cmake --skip-license 41 | RUN ln -s /opt/cmake/bin/cmake /usr/local/bin/cmake 42 | 43 | #install hyde dependencies 44 | RUN apt-get -y install libyaml-cpp-dev libboost-system-dev libboost-filesystem-dev 45 | 46 | COPY . /usr/src/hyde 47 | 48 | # build hyde and run the generate_test_files 49 | WORKDIR /usr/src/hyde 50 | RUN mkdir -p build \ 51 | && cd build \ 52 | && rm -rf * \ 53 | && cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release \ 54 | && ninja 55 | 56 | # install hyde 57 | RUN cp ./build/hyde /usr/bin 58 | 59 | # RUN apt-get -y install clang-15 60 | 61 | CMD ["./generate_test_files.sh"] 62 | 63 | # Experimenting with publishing the container and linking it to the hyde repo: 64 | 65 | LABEL org.opencontainers.image.source=https://github.com/adobe/hyde 66 | -------------------------------------------------------------------------------- /docs/libraries/functions.cpp/f_overloaded.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: function 3 | title: overloaded 4 | hyde: 5 | owner: __MISSING__ 6 | brief: __INLINED__ 7 | tags: 8 | - function 9 | inline: 10 | brief: _multiple descriptions_ 11 | defined_in_file: functions.cpp 12 | overloads: 13 | auto overloaded(int) -> float: 14 | arguments: 15 | - description: __OPTIONAL__ 16 | name: first 17 | type: int 18 | description: __INLINED__ 19 | inline: 20 | arguments: 21 | first: 22 | description: the first input parameter 23 | description: 24 | - an example unary overloaded function 25 | return: "`first`" 26 | return: __OPTIONAL__ 27 | signature_with_names: auto overloaded(int first) -> float 28 | auto overloaded(int, int) -> double: 29 | arguments: 30 | - description: __OPTIONAL__ 31 | name: first 32 | type: int 33 | - description: __OPTIONAL__ 34 | name: second 35 | type: int 36 | description: __INLINED__ 37 | inline: 38 | arguments: 39 | first: 40 | description: the first input parameter 41 | second: 42 | description: the second input parameter 43 | description: 44 | - an example binary overloaded function 45 | return: the product of `first` and `second` 46 | return: __OPTIONAL__ 47 | signature_with_names: auto overloaded(int first, int second) -> double 48 | auto overloaded(int, int, int) -> float: 49 | arguments: 50 | - description: __OPTIONAL__ 51 | name: first 52 | type: int 53 | - description: __OPTIONAL__ 54 | name: second 55 | type: int 56 | - description: __OPTIONAL__ 57 | name: third 58 | type: int 59 | description: __INLINED__ 60 | inline: 61 | arguments: 62 | first: 63 | description: the first input parameter 64 | second: 65 | description: the second input parameter 66 | third: 67 | description: the third input parameter 68 | description: 69 | - an example tertiary overloaded function 70 | return: the product of `first`, `second`, and `third` 71 | return: __OPTIONAL__ 72 | signature_with_names: auto overloaded(int first, int second, int third) -> float 73 | --- 74 | -------------------------------------------------------------------------------- /docs/images/site/hyde.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 27 | 30 | 33 | 36 | 37 | 38 | 39 | -------------------------------------------------------------------------------- /matchers/enum_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "enum_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 25 | // clang-format on 26 | 27 | // application 28 | #include "json.hpp" 29 | #include "matchers/utilities.hpp" 30 | 31 | using namespace clang; 32 | using namespace clang::ast_matchers; 33 | 34 | /**************************************************************************************************/ 35 | 36 | namespace hyde { 37 | 38 | /**************************************************************************************************/ 39 | 40 | void EnumInfo::run(const MatchFinder::MatchResult& Result) { 41 | auto enumeration = Result.Nodes.getNodeAs("enum"); 42 | auto info_opt = StandardDeclInfo(_options, enumeration); 43 | if (!info_opt) return; 44 | auto info = std::move(*info_opt); 45 | 46 | // info["scoped"] = enumeration->isScoped(); 47 | // info["fixed"] = enumeration->isFixed(); 48 | info["type"] = hyde::to_string(enumeration, enumeration->getIntegerType()); 49 | info["values"] = json::array(); 50 | 51 | for (const auto& p : enumeration->enumerators()) { 52 | json enumerator = json::object(); 53 | 54 | enumerator["name"] = p->getNameAsString(); 55 | 56 | if (auto comments = ProcessComments(p)) { 57 | enumerator["comments"] = std::move(*comments); 58 | } 59 | 60 | info["values"].push_back(std::move(enumerator)); 61 | } 62 | 63 | _j["enums"].push_back(std::move(info)); 64 | } 65 | 66 | /**************************************************************************************************/ 67 | 68 | } // namespace hyde 69 | 70 | /**************************************************************************************************/ 71 | -------------------------------------------------------------------------------- /test_files/functions.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | //------------------------------------------------------------------------------------------------------------------------------------------ 13 | 14 | /// an example nullary function. 15 | /// @return `0` 16 | int nullary_function_example() { return 0; } 17 | 18 | 19 | /// an example binary function. 20 | /// @param first the first input 21 | /// @param second the second input 22 | /// @return The sum of the two input parameters. 23 | int binary_function_example(int first, int second) { return 0; } 24 | 25 | 26 | /// an example unary overloaded function 27 | /// @param first the first input parameter 28 | /// @return `first` 29 | auto overloaded(int first) -> float { return first; } 30 | 31 | /// an example binary overloaded function 32 | /// @param first the first input parameter 33 | /// @param second the second input parameter 34 | /// @return the product of `first` and `second` 35 | auto overloaded(int first, int second) -> double { return first * second; } 36 | 37 | /// an example tertiary overloaded function 38 | /// @param first the first input parameter 39 | /// @param second the second input parameter 40 | /// @param third the third input parameter 41 | /// @return the product of `first`, `second`, and `third` 42 | auto overloaded(int first, int second, int third) -> float { return first * second * third; } 43 | 44 | 45 | /// an example static function 46 | /// @return `0` 47 | static int static_function_example() { return 0; } 48 | 49 | 50 | /// an example static function with `auto` return type 51 | /// @return `0` 52 | static auto static_auto_function_example() { return 0; } 53 | 54 | 55 | /// an example static function with trailing return type 56 | /// @return `0` 57 | static auto static_trailing_type_function_example() -> int { return 0; } 58 | 59 | 60 | /// an example template function, deleted by default 61 | /// @return Not applicable, seeing that the default definition has been deleted. 62 | template 63 | T template_function_example() = delete; 64 | 65 | /// an example specialization of the template function example 66 | /// @return Forty-two 67 | template <> 68 | int template_function_example() { 69 | return 42; 70 | } 71 | 72 | //------------------------------------------------------------------------------------------------------------------------------------------ 73 | -------------------------------------------------------------------------------- /test_files/point.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // AST dump with 13 | // clang --std=c++1z -Xclang -ast-dump -fsyntax-only ./test_files/pod.cpp 14 | 15 | #include 16 | 17 | //------------------------------------------------------------------------------------------------------------------------------------------ 18 | 19 | /// @brief An example point class 20 | template 21 | struct point { 22 | /// The `x` coordinate of the point. 23 | T x{0}; 24 | /// The `y` coordinate of the point. 25 | T y{0}; 26 | 27 | /// A static routine that returns the origin point. 28 | /// @return The point `(0, 0)` 29 | static constexpr auto origin() { return point(); } 30 | 31 | 32 | /// Default constructor of default definition. 33 | constexpr point() noexcept = default; 34 | 35 | /// Value-based constructor that takes `x` and `y` values and sinks them into place. 36 | /// @param _x The `x` coordinate to sink. 37 | /// @param _y The `y` coordinate to sink. 38 | constexpr point(T _x, T _y) noexcept : x(std::move(_x)), y(std::move(_y)) {} 39 | 40 | /// Equality operator. 41 | /// @return `true` iff the two points' `x` and `y` coordinates are memberwise equal. 42 | friend inline constexpr bool operator==(const point& a, const point& b) { 43 | return (a.x == b.x) && (a.y == b.y); 44 | } 45 | 46 | /// Inequality operator. 47 | /// @return `true` iff the two points' `x` or `y` coordinates are memberwise inequal. 48 | friend inline constexpr bool operator!=(const point& a, const point& b) { return !(a == b); } 49 | 50 | /// Subtraction operator. 51 | /// @param a The point to be subtracted from. 52 | /// @param b The point to subtract. 53 | /// @return A new point whose axis values are subtractions of the two inputs' axis values. 54 | friend inline constexpr point operator-(const point& a, const point& b) { 55 | return point(a.x - b.x, a.y - b.y); 56 | } 57 | 58 | /// Subtraction-assignment operator. 59 | /// @param a The point to subtract from this point 60 | /// @return A reference to `this`. 61 | constexpr point& operator-=(const point& a) { 62 | x -= a.x; 63 | y -= a.y; 64 | return *this; 65 | } 66 | }; 67 | 68 | //------------------------------------------------------------------------------------------------------------------------------------------ 69 | -------------------------------------------------------------------------------- /test_files/typedef_and_alias.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // AST dump with 13 | // TERM="" clang --std=c++1z -Xclang -ast-dump -fsyntax-only -fparse-all-comments -fcomment-block-commands=hyde ./typedef_and_alias.cpp 14 | 15 | //------------------------------------------------------------------------------------------------------------------------------------------ 16 | 17 | /// Example typedef expression whose underlying type is `int`. 18 | typedef int typedef_example; 19 | 20 | /// Example using expression whose underlying type is `int`. 21 | using using_example = int; 22 | 23 | //------------------------------------------------------------------------------------------------------------------------------------------ 24 | 25 | /// @brief Example class with two type definitions 26 | template 27 | struct template_example { 28 | /// Type derived from the first template parameter. 29 | typedef T typedef_from_T; 30 | /// Type derived from the second template parameter. 31 | using using_from_U = U; 32 | }; 33 | 34 | //------------------------------------------------------------------------------------------------------------------------------------------ 35 | 36 | /// Partial specialization of the above `template_example` template 37 | template 38 | using using_partial_specialization_example = template_example; 39 | 40 | /// Full specialization of the above partial specialization 41 | using using_full_specialization_example = using_partial_specialization_example; 42 | 43 | /// Using typedef to define another full specialization of the above partial specialization 44 | typedef using_partial_specialization_example typedef_full_specialization_example; 45 | 46 | //------------------------------------------------------------------------------------------------------------------------------------------ 47 | 48 | /// @brief Example struct that leverages type aliases defined above. 49 | struct template_example_instantiator { 50 | /// Example partial specialization 51 | template 52 | using using_partial_specialization_example = template_example; 53 | 54 | /// Example full specialization 55 | using using_full_specialization_example = using_partial_specialization_example; 56 | 57 | /// Example partial specialization using `typedef` 58 | typedef using_partial_specialization_example typedef_full_specialization_example; 59 | }; 60 | 61 | //------------------------------------------------------------------------------------------------------------------------------------------ 62 | -------------------------------------------------------------------------------- /emitters/yaml_base_emitter_fwd.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | #include 17 | #include 18 | 19 | // application 20 | #include "json.hpp" 21 | 22 | /**************************************************************************************************/ 23 | 24 | namespace hyde { 25 | 26 | /**************************************************************************************************/ 27 | 28 | static constexpr char const* tag_value_missing_k = "__MISSING__"; 29 | static constexpr char const* tag_value_optional_k = "__OPTIONAL__"; 30 | static constexpr char const* tag_value_deprecated_k = "__DEPRECATED__"; 31 | static constexpr char const* tag_value_inlined_k = "__INLINED__"; 32 | static constexpr char const* index_filename_k = "index.md"; 33 | 34 | /**************************************************************************************************/ 35 | 36 | enum class attribute_category { disabled, required, optional, deprecated, inlined }; 37 | 38 | static constexpr char const* get_tag(attribute_category c) { 39 | switch (c) { 40 | case attribute_category::required: 41 | return tag_value_missing_k; 42 | case attribute_category::optional: 43 | return tag_value_optional_k; 44 | case attribute_category::deprecated: 45 | return tag_value_deprecated_k; 46 | case attribute_category::inlined: 47 | return tag_value_inlined_k; 48 | default: 49 | throw std::invalid_argument("unexpected attribute category"); 50 | } 51 | } 52 | 53 | static inline bool is_tag(const std::string& s) { return s.substr(0, 2) == "__"; } 54 | 55 | /**************************************************************************************************/ 56 | 57 | struct emit_options { 58 | attribute_category _tested_by{attribute_category::disabled}; 59 | bool _ignore_extraneous_files{false}; 60 | }; 61 | 62 | /**************************************************************************************************/ 63 | 64 | struct documentation { 65 | json _json; 66 | std::string _remainder; 67 | bool _error{false}; 68 | }; 69 | 70 | documentation parse_documentation(const std::filesystem::path& path, bool fixup_subfield); 71 | 72 | /// @return `true` on failure to write, `false` otherwise. 73 | bool write_documentation(const documentation& docs, const std::filesystem::path& path); 74 | 75 | /**************************************************************************************************/ 76 | 77 | } // namespace hyde 78 | 79 | /**************************************************************************************************/ 80 | -------------------------------------------------------------------------------- /test_files/comments.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // AST dump with 13 | // TERM="" clang --std=c++1z -Xclang -ast-dump -fsyntax-only -fparse-all-comments -fcomment-block-commands=hyde ./comments.cpp 14 | 15 | /// @brief Sample class intended to exhibit docs for compiler-generated routines 16 | /// @hyde-owner fosterbrereton 17 | struct compiler_generated { 18 | compiler_generated() = delete; 19 | compiler_generated(const compiler_generated&) = default; 20 | 21 | /// This definition will force the compiler to auto-generate this class' assignment operator. 22 | void assign(const compiler_generated& rhs) { 23 | *this = rhs; 24 | } 25 | }; 26 | 27 | /// An example struct from which these commands will hang. 28 | /// @brief This is a sample brief. 29 | /// @warning This is a sample warning. 30 | /// @par header This is a sample paragraph. 31 | /// @hyde-owner fosterbrereton 32 | /// @see [Slides](https://llvm.org/devmtg/2012-11/Gribenko_CommentParsing.pdf) from an LLVM dev meeting chat on the comment parsing feature 33 | struct some_struct { 34 | virtual ~some_struct() = delete; 35 | 36 | /// This is a longer description of this function that does things as well as it does. 37 | /// Notice how long this comment is! So impressive. 💥 38 | /// @brief A function that does a thing, and does it well. 39 | /// @param[in] input an input parameter 40 | /// @param[in,out] input_output a bidirectional parameter 41 | /// @param[out] output an output parameter 42 | /// @pre An example precondition. 43 | /// @post An example postcondition. 44 | /// @return Some additional value. 45 | /// @throw `std::runtime_error` if the function actually _can't_ do the thing. Sorry! 46 | /// @todo This really could use some cleanup. Although, its implementation doesn't exist... 47 | /// @warning This function may be very expensive to run. Do not call it inside a loop. 48 | int some_function(int input, int& input_output, int& output); 49 | 50 | /// A virtual function that intends to be overridden. 51 | virtual void virtual_function(); 52 | 53 | int _x{0}; ///< A trailing comment that documents `_x`. 54 | }; 55 | 56 | /// Notice how many of the comments for this structure are inherited from its superclass. 57 | /// @brief This is a sample brief for `some_other_struct` 58 | struct some_other_struct : public some_struct { 59 | void virtual_function() override; 60 | }; 61 | 62 | /// @brief some template function 63 | /// @tparam T The type of thing being returned 64 | /// @return an instance of type `T` 65 | template 66 | T template_function(); 67 | 68 | //------------------------------------------------------------------------------------------------------------------------------------------ 69 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Adobe Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as 6 | contributors and maintainers pledge to making participation in our project and 7 | our community a harassment-free experience for everyone, regardless of age, body 8 | size, disability, ethnicity, gender identity and expression, level of experience, 9 | nationality, personal appearance, race, religion, or sexual identity and 10 | orientation. 11 | 12 | ## Our Standards 13 | 14 | Examples of behavior that contributes to creating a positive environment 15 | include: 16 | 17 | * Using welcoming and inclusive language 18 | * Being respectful of differing viewpoints and experiences 19 | * Gracefully accepting constructive criticism 20 | * Focusing on what is best for the community 21 | * Showing empathy towards other community members 22 | 23 | Examples of unacceptable behavior by participants include: 24 | 25 | * The use of sexualized language or imagery and unwelcome sexual attention or 26 | advances 27 | * Trolling, insulting/derogatory comments, and personal or political attacks 28 | * Public or private harassment 29 | * Publishing others' private information, such as a physical or electronic 30 | address, without explicit permission 31 | * Other conduct which could reasonably be considered inappropriate in a 32 | professional setting 33 | 34 | ## Our Responsibilities 35 | 36 | Project maintainers are responsible for clarifying the standards of acceptable 37 | behavior and are expected to take appropriate and fair corrective action in 38 | response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or 41 | reject comments, commits, code, wiki edits, issues, and other contributions 42 | that are not aligned to this Code of Conduct, or to ban temporarily or 43 | permanently any contributor for other behaviors that they deem inappropriate, 44 | threatening, offensive, or harmful. 45 | 46 | ## Scope 47 | 48 | This Code of Conduct applies both within project spaces and in public spaces 49 | when an individual is representing the project or its community. Examples of 50 | representing a project or community include using an official project e-mail 51 | address, posting via an official social media account, or acting as an appointed 52 | representative at an online or offline event. Representation of a project may be 53 | further defined and clarified by project maintainers. 54 | 55 | ## Enforcement 56 | 57 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 58 | reported by contacting the project team at Grp-opensourceoffice@adobe.com. All 59 | complaints will be reviewed and investigated and will result in a response that 60 | is deemed necessary and appropriate to the circumstances. The project team is 61 | obligated to maintain confidentiality with regard to the reporter of an incident. 62 | Further details of specific enforcement policies may be posted separately. 63 | 64 | Project maintainers who do not follow or enforce the Code of Conduct in good 65 | faith may face temporary or permanent repercussions as determined by other 66 | members of the project's leadership. 67 | 68 | ## Attribution 69 | 70 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, 71 | available at [http://contributor-covenant.org/version/1/4][version] 72 | 73 | [homepage]: http://contributor-covenant.org 74 | [version]: http://contributor-covenant.org/version/1/4/ 75 | -------------------------------------------------------------------------------- /.clang-format: -------------------------------------------------------------------------------- 1 | # Format style options described here: 2 | # https://clang.llvm.org/docs/ClangFormatStyleOptions.html 3 | 4 | # Many of the alignment and single line changes were made to facilitate setting 5 | # breakpoints on specific expressions. 6 | 7 | --- 8 | AccessModifierOffset: -4 9 | AlignAfterOpenBracket: Align 10 | AlignConsecutiveAssignments: false 11 | AlignConsecutiveDeclarations: false 12 | AlignEscapedNewlinesLeft: true 13 | AlignOperands: true 14 | AlignTrailingComments: true 15 | AllowAllParametersOfDeclarationOnNextLine: true 16 | AllowShortBlocksOnASingleLine: false 17 | AllowShortCaseLabelsOnASingleLine: false 18 | AllowShortFunctionsOnASingleLine: All 19 | AllowShortIfStatementsOnASingleLine: true 20 | AllowShortLoopsOnASingleLine: false 21 | # AlwaysBreakAfterDefinitionReturnType: TopLevel 22 | AlwaysBreakAfterReturnType: None 23 | AlwaysBreakBeforeMultilineStrings: false 24 | AlwaysBreakTemplateDeclarations: true 25 | BinPackArguments: true 26 | BinPackParameters: false 27 | # BraceWrapping: 28 | # AfterClass: true 29 | # AfterControlStatement: false 30 | # AfterEnum: false 31 | # AfterFunction: false 32 | # AfterNamespace: false 33 | # AfterObjCDeclaration: false 34 | # AfterStruct: false 35 | # AfterUnion: false 36 | # BeforeCatch: false 37 | # BeforeElse: false 38 | # IndentBraces: false 39 | BreakBeforeBinaryOperators: None 40 | BreakBeforeBraces: Attach 41 | BreakBeforeInheritanceComma: true 42 | BreakBeforeTernaryOperators: false 43 | BreakConstructorInitializersBeforeComma: false 44 | BreakAfterJavaFieldAnnotations: false 45 | BreakStringLiterals: false 46 | ColumnLimit: 100 47 | CommentPragmas: '^ IWYU pragma:' 48 | ConstructorInitializerAllOnOneLineOrOnePerLine: false 49 | ConstructorInitializerIndentWidth: 4 50 | ContinuationIndentWidth: 4 51 | Cpp11BracedListStyle: true 52 | DerivePointerAlignment: false 53 | DisableFormat: false 54 | ExperimentalAutoDetectBinPacking: false 55 | FixNamespaceComments: true 56 | ForEachMacros: [ foreach, Q_FOREACH, BOOST_FOREACH ] 57 | IncludeCategories: 58 | - Regex: '^"(llvm|llvm-c|clang|clang-c)/' 59 | Priority: 2 60 | - Regex: '^(<|"(gtest|isl|json)/)' 61 | Priority: 3 62 | - Regex: '.*' 63 | Priority: 1 64 | IncludeIsMainRegex: '$' 65 | IndentCaseLabels: true 66 | IndentWidth: 4 67 | IndentWrappedFunctionNames: true 68 | JavaScriptQuotes: Leave 69 | JavaScriptWrapImports: true 70 | KeepEmptyLinesAtTheStartOfBlocks: false 71 | MacroBlockBegin: '' 72 | MacroBlockEnd: '' 73 | MaxEmptyLinesToKeep: 1 74 | NamespaceIndentation: None 75 | ObjCBlockIndentWidth: 4 76 | ObjCSpaceAfterProperty: true 77 | ObjCSpaceBeforeProtocolList: true 78 | PenaltyBreakBeforeFirstCallParameter: 19 79 | PenaltyBreakComment: 300 80 | PenaltyBreakFirstLessLess: 120 81 | PenaltyBreakString: 1000 82 | PenaltyExcessCharacter: 1000000 83 | PenaltyReturnTypeOnItsOwnLine: 1000 84 | PointerAlignment: Left 85 | ReflowComments: true 86 | SortIncludes: true 87 | SpaceAfterCStyleCast: false 88 | SpaceAfterTemplateKeyword: true 89 | SpaceBeforeAssignmentOperators: true 90 | SpaceBeforeParens: ControlStatements 91 | SpaceInEmptyParentheses: false 92 | SpacesBeforeTrailingComments: 1 93 | SpacesInAngles: false 94 | SpacesInContainerLiterals: true 95 | SpacesInCStyleCastParentheses: false 96 | SpacesInParentheses: false 97 | SpacesInSquareBrackets: false 98 | Standard: Cpp11 99 | TabWidth: 4 100 | UseTab: Never 101 | --- 102 | Language: Cpp 103 | --- 104 | Language: ObjC 105 | PointerAlignment: Right 106 | ... 107 | -------------------------------------------------------------------------------- /emitters/yaml_sourcefile_emitter.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "yaml_sourcefile_emitter.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | bool yaml_sourcefile_emitter::do_merge(const std::string& filepath, 25 | const json& have, 26 | const json& expected, 27 | json& out_merged) { 28 | bool failure{false}; 29 | 30 | failure |= check_scalar(filepath, have, expected, "", out_merged, "library-type"); 31 | failure |= check_typedefs(filepath, have, expected, "", out_merged); 32 | 33 | return failure; 34 | } 35 | 36 | /**************************************************************************************************/ 37 | 38 | bool yaml_sourcefile_emitter::emit(const json& j, json& out_emitted, const json& inherited) { 39 | const auto sub_path = 40 | subcomponent(static_cast(j["paths"]["src_path"]), _src_root); 41 | json node = 42 | base_emitter_node("library", sub_path.string(), "sourcefile", has_json_flag(j, "implicit")); 43 | node["hyde"]["library-type"] = "sourcefile"; 44 | 45 | insert_typedefs(j, node, inherited); 46 | 47 | _sub_dst = dst_path(j, sub_path); 48 | 49 | return reconcile(std::move(node), _dst_root, _sub_dst / index_filename_k, out_emitted); 50 | } 51 | 52 | /**************************************************************************************************/ 53 | 54 | bool yaml_sourcefile_emitter::extraneous_file_check_internal(const std::filesystem::path& root, 55 | const std::filesystem::path& path) { 56 | bool failure{false}; 57 | std::filesystem::directory_iterator first(path); 58 | std::filesystem::directory_iterator last; 59 | 60 | while (first != last) { 61 | const auto& entry = *first; 62 | 63 | if (!checker_s.checked(entry)) { 64 | std::filesystem::path entry_path(entry); 65 | if (entry_path.filename() == ".DS_Store") { 66 | std::cerr << entry_path.string() << ": Unintended OS file (not a failure)\n"; 67 | } else if (entry_path.extension() != ".cpp") { 68 | // We need better validation here against the existence of example (cpp) files. 69 | std::cerr << entry_path.string() << ": extraneous file\n"; 70 | failure = true; 71 | } 72 | } 73 | 74 | if (is_directory(entry)) { 75 | failure |= extraneous_file_check_internal(root, entry); 76 | } 77 | 78 | ++first; 79 | } 80 | 81 | return failure; 82 | } 83 | 84 | /**************************************************************************************************/ 85 | 86 | bool yaml_sourcefile_emitter::extraneous_file_check() { 87 | return extraneous_file_check_internal(_sub_dst, _sub_dst); 88 | } 89 | 90 | /**************************************************************************************************/ 91 | 92 | } // namespace hyde 93 | 94 | /**************************************************************************************************/ 95 | -------------------------------------------------------------------------------- /sources/output_yaml.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "output_yaml.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // yaml-cpp 19 | #include "yaml-cpp/yaml.h" 20 | 21 | // application 22 | #include "emitters/yaml_class_emitter.hpp" 23 | #include "emitters/yaml_enum_emitter.hpp" 24 | #include "emitters/yaml_function_emitter.hpp" 25 | #include "emitters/yaml_library_emitter.hpp" 26 | #include "emitters/yaml_sourcefile_emitter.hpp" 27 | #include "json.hpp" 28 | 29 | /**************************************************************************************************/ 30 | 31 | namespace hyde { 32 | 33 | /**************************************************************************************************/ 34 | 35 | void output_yaml(json j, 36 | const std::filesystem::path& src_root, 37 | const std::filesystem::path& dst_root, 38 | json& out_emitted, 39 | yaml_mode mode, 40 | const emit_options& options) { 41 | bool failure{false}; 42 | auto& library_emitted = out_emitted; 43 | const json no_inheritance_k; 44 | 45 | // Process top-level library 46 | yaml_library_emitter(src_root, dst_root, mode, options).emit(j, library_emitted, no_inheritance_k); 47 | 48 | // Process sourcefile 49 | yaml_sourcefile_emitter sourcefile_emitter(src_root, dst_root, mode, options); 50 | auto sourcefile_emitted = hyde::json::object(); 51 | failure |= sourcefile_emitter.emit(j, sourcefile_emitted, no_inheritance_k); 52 | 53 | // Process classes 54 | yaml_class_emitter class_emitter(src_root, dst_root, mode, options); 55 | for (const auto& c : j["classes"]) { 56 | auto class_emitted = hyde::json::object(); 57 | failure |= class_emitter.emit(c, class_emitted, no_inheritance_k); 58 | sourcefile_emitted["classes"].push_back(std::move(class_emitted)); 59 | } 60 | 61 | // Process enums 62 | yaml_enum_emitter enum_emitter(src_root, dst_root, mode, options); 63 | for (const auto& c : j["enums"]) { 64 | auto enum_emitted = hyde::json::object(); 65 | failure |= enum_emitter.emit(c, enum_emitted, no_inheritance_k); 66 | sourcefile_emitted["enums"].push_back(std::move(enum_emitted)); 67 | } 68 | 69 | // Process functions 70 | yaml_function_emitter function_emitter(src_root, dst_root, mode, options, false); 71 | const auto& functions = j["functions"]; 72 | for (auto it = functions.begin(); it != functions.end(); ++it) { 73 | function_emitter.set_key(it.key()); 74 | auto function_emitted = hyde::json::object(); 75 | failure |= function_emitter.emit(it.value(), function_emitted, no_inheritance_k); 76 | sourcefile_emitted["functions"].push_back(std::move(function_emitted)); 77 | } 78 | 79 | library_emitted["sourcefiles"].push_back(std::move(sourcefile_emitted)); 80 | 81 | // Check for extra files. Always do this last. 82 | if (!options._ignore_extraneous_files) { 83 | failure |= sourcefile_emitter.extraneous_file_check(); 84 | } 85 | 86 | if (failure && mode == yaml_mode::validate) 87 | throw std::runtime_error("YAML documentation failed to validate."); 88 | } 89 | 90 | /**************************************************************************************************/ 91 | 92 | } // namespace hyde 93 | 94 | /**************************************************************************************************/ 95 | -------------------------------------------------------------------------------- /emitters/yaml_enum_emitter.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "yaml_enum_emitter.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | /**************************************************************************************************/ 19 | 20 | namespace hyde { 21 | 22 | /**************************************************************************************************/ 23 | 24 | bool yaml_enum_emitter::do_merge(const std::string& filepath, 25 | const json& have, 26 | const json& expected, 27 | json& out_merged) { 28 | bool failure{false}; 29 | 30 | failure |= check_scalar(filepath, have, expected, "", out_merged, "defined_in_file"); 31 | failure |= check_scalar_array(filepath, have, expected, "", out_merged, "annotation"); 32 | failure |= check_scalar_array(filepath, have, expected, "", out_merged, "namespace"); 33 | 34 | failure |= check_object_array( 35 | filepath, have, expected, "", out_merged, "values", "name", 36 | [this](const std::string& filepath, const json& have, const json& expected, 37 | const std::string& nodepath, json& out_merged) { 38 | bool failure{false}; 39 | 40 | failure |= check_scalar(filepath, have, expected, nodepath, out_merged, "name"); 41 | failure |= check_editable_scalar(filepath, have, expected, nodepath, out_merged, 42 | "description"); 43 | failure |= check_scalar_array(filepath, have, expected, "", out_merged, "values"); 44 | 45 | check_inline_comments(expected, out_merged); 46 | 47 | return failure; 48 | }); 49 | 50 | check_inline_comments(expected, out_merged); 51 | 52 | return failure; 53 | } 54 | 55 | /**************************************************************************************************/ 56 | 57 | bool yaml_enum_emitter::emit(const json& j, json& out_emitted, const json& inherited) { 58 | const std::string& name = j["name"]; 59 | 60 | // Most likely an enum forward declaration. Nothing to document here. 61 | if (j["values"].empty()) return true; 62 | 63 | json base_node = 64 | base_emitter_node("enumeration", j["name"], "enumeration", has_json_flag(j, "implicit")); 65 | json& node = base_node["hyde"]; 66 | 67 | insert_inherited(inherited, node); 68 | insert_annotations(j, node); 69 | insert_doxygen(j, node); 70 | 71 | if (has_inline_field(node, "owner")) { 72 | node["owner"] = tag_value_inlined_k; 73 | } 74 | 75 | if (has_inline_field(node, "brief")) { 76 | node["brief"] = tag_value_inlined_k; 77 | } 78 | 79 | node["defined_in_file"] = defined_in_file(j["defined_in_file"], _src_root); 80 | 81 | std::string filename; 82 | for (const auto& ns : j["namespaces"]) { 83 | const std::string& namespace_str = ns; 84 | node["namespace"].push_back(namespace_str); 85 | filename += namespace_str + "::"; 86 | } 87 | filename = filename_filter(std::move(filename) + name) + ".md"; 88 | 89 | for (const auto& value : j["values"]) { 90 | json cur_value; 91 | insert_doxygen(value, cur_value); 92 | 93 | cur_value["name"] = value["name"]; 94 | cur_value["description"] = 95 | has_inline_field(cur_value, "description") ? tag_value_inlined_k : tag_value_missing_k; 96 | node["values"].push_back(std::move(cur_value)); 97 | } 98 | 99 | return reconcile(std::move(base_node), _dst_root, dst_path(j) / filename, out_emitted); 100 | } 101 | 102 | /**************************************************************************************************/ 103 | 104 | } // namespace hyde 105 | 106 | /**************************************************************************************************/ 107 | -------------------------------------------------------------------------------- /docs/libraries/classes.cpp/class_example/m_overloaded.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: method 3 | title: overloaded 4 | hyde: 5 | owner: __INLINED__ 6 | brief: __INLINED__ 7 | tags: 8 | - method 9 | inline: 10 | brief: _multiple descriptions_ 11 | owner: fosterbrereton 12 | defined_in_file: classes.cpp 13 | overloads: 14 | void overloaded(): 15 | annotation: 16 | - deprecated 17 | description: __INLINED__ 18 | inline: 19 | description: 20 | - a deprecated overload that takes zero parameters. 21 | return: __OPTIONAL__ 22 | signature_with_names: void overloaded() 23 | void overloaded(const std::string &): 24 | arguments: 25 | - description: __OPTIONAL__ 26 | name: first 27 | type: const std::string & 28 | description: __INLINED__ 29 | inline: 30 | arguments: 31 | first: 32 | description: the first parameter of the first overload. 33 | brief: A series of overloaded functions. 34 | description: 35 | - an overloaded member function that takes one parameter. 36 | return: __OPTIONAL__ 37 | signature_with_names: void overloaded(const std::string & first) 38 | void overloaded(const std::string &, class_example *, int): 39 | arguments: 40 | - description: __OPTIONAL__ 41 | name: unnamed-0 42 | type: const std::string & 43 | unnamed: true 44 | - description: __OPTIONAL__ 45 | name: unnamed-1 46 | type: class_example * 47 | unnamed: true 48 | - description: __OPTIONAL__ 49 | name: unnamed-2 50 | type: int 51 | unnamed: true 52 | description: __INLINED__ 53 | inline: 54 | description: 55 | - 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. 56 | return: __OPTIONAL__ 57 | signature_with_names: void overloaded(const std::string &, class_example *, int) 58 | void overloaded(const std::string &, class_example *, int, bool, std::size_t): 59 | arguments: 60 | - description: __OPTIONAL__ 61 | name: first 62 | type: const std::string & 63 | - description: __OPTIONAL__ 64 | name: second 65 | type: class_example * 66 | - description: __OPTIONAL__ 67 | name: third 68 | type: int 69 | - description: __OPTIONAL__ 70 | name: fourth 71 | type: bool 72 | - description: __OPTIONAL__ 73 | name: fifth 74 | type: std::size_t 75 | description: __INLINED__ 76 | inline: 77 | arguments: 78 | fifth: 79 | description: the fifth parameter of the fourth overload. 80 | first: 81 | description: the first parameter of the fourth overload. 82 | fourth: 83 | description: the fourth parameter of the fourth overload. 84 | second: 85 | description: the second parameter of the fourth overload. 86 | third: 87 | description: the third parameter of the fourth overload. 88 | description: 89 | - an overloaded member function that takes _five_ parameters. 90 | return: __OPTIONAL__ 91 | signature_with_names: void overloaded(const std::string & first, class_example * second, int third, bool fourth, std::size_t fifth) 92 | void overloaded(const std::string &, const std::string &) volatile: 93 | arguments: 94 | - description: __OPTIONAL__ 95 | name: first 96 | type: const std::string & 97 | - description: __OPTIONAL__ 98 | name: second 99 | type: const std::string & 100 | description: __INLINED__ 101 | inline: 102 | arguments: 103 | first: 104 | description: the first parameter of the second overload. 105 | second: 106 | description: the second parameter of the second overload. 107 | brief: Another brief describing one of the overloaded functions. 108 | description: 109 | - an overloaded member function that takes two parameters. 110 | return: __OPTIONAL__ 111 | signature_with_names: void overloaded(const std::string & first, const std::string & second) volatile 112 | void overloaded(const std::string &, std::vector) const: 113 | arguments: 114 | - description: __OPTIONAL__ 115 | name: first 116 | type: const std::string & 117 | - description: __OPTIONAL__ 118 | name: second 119 | type: std::vector 120 | description: __INLINED__ 121 | inline: 122 | arguments: 123 | first: 124 | description: the first parameter of the third overload. 125 | second: 126 | description: the second parameter of the third overload. 127 | description: 128 | - another overloaded member function that takes two parameters. 129 | return: __OPTIONAL__ 130 | signature_with_names: void overloaded(const std::string & first, std::vector second) const 131 | --- 132 | -------------------------------------------------------------------------------- /CMakeLists.txt: -------------------------------------------------------------------------------- 1 | # Copyright 2018 Adobe 2 | # All Rights Reserved. 3 | 4 | # NOTICE: Adobe permits you to use, modify, and distribute this file in 5 | # accordance with the terms of the Adobe license agreement accompanying 6 | # it. If you have received this file from a source other than Adobe, 7 | # then your use, modification, or distribution of it requires the prior 8 | # written permission of Adobe. 9 | 10 | cmake_minimum_required(VERSION 3.23) 11 | 12 | set(CMAKE_POLICY_DEFAULT_CMP0077 NEW) # Avoid overriding normal variables with option() 13 | set(CMAKE_POLICY_DEFAULT_CMP0126 NEW) # Avoid overriding normal variables with set(CACHE) 14 | 15 | include(FetchContent) 16 | 17 | set(FETCHCONTENT_QUIET FALSE) 18 | 19 | set(CMAKE_OSX_ARCHITECTURES "x86_64;arm64") 20 | 21 | project(hyde) 22 | 23 | set(CMAKE_CXX_STANDARD 20) 24 | set(CMAKE_CXX_EXTENSIONS OFF) 25 | set(CMAKE_CXX_STANDARD_REQUIRED ON) 26 | set(CMAKE_XCODE_GENERATE_SCHEME OFF) 27 | 28 | message(STATUS "INFO: Setting up LLVM...") 29 | 30 | FetchContent_Declare( 31 | llvm 32 | GIT_REPOSITORY https://github.com/llvm/llvm-project.git 33 | GIT_TAG 3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff # llvmorg-18.1.8 34 | GIT_SHALLOW TRUE 35 | GIT_PROGRESS TRUE 36 | SOURCE_SUBDIR llvm 37 | ) 38 | 39 | FetchContent_Declare( 40 | diff 41 | GIT_REPOSITORY https://github.com/fosterbrereton/diff.git 42 | GIT_TAG 2ba1687a30de266416caa141f8be408e72843be0 43 | GIT_SHALLOW TRUE 44 | GIT_PROGRESS TRUE 45 | SOURCE_SUBDIR diff 46 | ) 47 | 48 | set(LLVM_ENABLE_PROJECTS "clang") 49 | set(LLVM_TARGETS_TO_BUILD "X86;AArch64") 50 | set(LLVM_ENABLE_ZSTD OFF) 51 | 52 | FetchContent_MakeAvailable(llvm) 53 | FetchContent_MakeAvailable(diff) 54 | 55 | message(STATUS "INFO: LLVM source dir: ${llvm_SOURCE_DIR}") 56 | message(STATUS "INFO: LLVM binary dir: ${llvm_BINARY_DIR}") 57 | 58 | add_executable(hyde) 59 | 60 | set(SRC_SOURCES 61 | ${PROJECT_SOURCE_DIR}/sources/autodetect.cpp 62 | ${PROJECT_SOURCE_DIR}/sources/main.cpp 63 | ${PROJECT_SOURCE_DIR}/sources/output_yaml.cpp 64 | ) 65 | 66 | set(SRC_EMITTERS 67 | ${PROJECT_SOURCE_DIR}/emitters/yaml_base_emitter.cpp 68 | ${PROJECT_SOURCE_DIR}/emitters/yaml_class_emitter.cpp 69 | ${PROJECT_SOURCE_DIR}/emitters/yaml_enum_emitter.cpp 70 | ${PROJECT_SOURCE_DIR}/emitters/yaml_function_emitter.cpp 71 | ${PROJECT_SOURCE_DIR}/emitters/yaml_library_emitter.cpp 72 | ${PROJECT_SOURCE_DIR}/emitters/yaml_sourcefile_emitter.cpp 73 | ) 74 | 75 | set(SRC_MATCHERS 76 | ${PROJECT_SOURCE_DIR}/matchers/class_matcher.cpp 77 | ${PROJECT_SOURCE_DIR}/matchers/enum_matcher.cpp 78 | ${PROJECT_SOURCE_DIR}/matchers/function_matcher.cpp 79 | ${PROJECT_SOURCE_DIR}/matchers/namespace_matcher.cpp 80 | ${PROJECT_SOURCE_DIR}/matchers/typealias_matcher.cpp 81 | ${PROJECT_SOURCE_DIR}/matchers/typedef_matcher.cpp 82 | ${PROJECT_SOURCE_DIR}/matchers/utilities.cpp 83 | ) 84 | 85 | set(SRC_YAMLCPP 86 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/binary.cpp 87 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/convert.cpp 88 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/depthguard.cpp 89 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/directives.cpp 90 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/emit.cpp 91 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/emitfromevents.cpp 92 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/emitter.cpp 93 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/emitterstate.cpp 94 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/emitterutils.cpp 95 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/exceptions.cpp 96 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/exp.cpp 97 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/memory.cpp 98 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/node.cpp 99 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/node_data.cpp 100 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/nodebuilder.cpp 101 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/nodeevents.cpp 102 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/null.cpp 103 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/ostream_wrapper.cpp 104 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/parse.cpp 105 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/parser.cpp 106 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/regex_yaml.cpp 107 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/scanner.cpp 108 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/scanscalar.cpp 109 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/scantag.cpp 110 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/scantoken.cpp 111 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/simplekey.cpp 112 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/singledocparser.cpp 113 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/stream.cpp 114 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/src/tag.cpp 115 | ) 116 | 117 | target_sources(hyde 118 | PRIVATE 119 | ${SRC_SOURCES} 120 | ${SRC_EMITTERS} 121 | ${SRC_MATCHERS} 122 | ${SRC_YAMLCPP} 123 | ) 124 | 125 | source_group(sources FILES ${SRC_SOURCES}) 126 | source_group(emitters FILES ${SRC_EMITTERS}) 127 | source_group(matchers FILES ${SRC_MATCHERS}) 128 | source_group(yaml-cpp FILES ${SRC_YAMLCPP}) 129 | 130 | target_include_directories(hyde 131 | PUBLIC 132 | ${CMAKE_CURRENT_SOURCE_DIR} 133 | ${CMAKE_CURRENT_SOURCE_DIR}/include 134 | ${PROJECT_SOURCE_DIR}/submodules/yaml-cpp/include/ 135 | ${PROJECT_SOURCE_DIR}/submodules/json/include/ 136 | ${llvm_SOURCE_DIR}/clang/include 137 | ${llvm_BINARY_DIR}/tools/clang/include 138 | ${llvm_SOURCE_DIR}/llvm/include 139 | ${llvm_BINARY_DIR}/include 140 | ${diff_SOURCE_DIR}/include 141 | ) 142 | 143 | target_compile_options(hyde 144 | PUBLIC 145 | -Wall 146 | -Wno-comment 147 | -Werror 148 | -Wno-range-loop-analysis 149 | ) 150 | 151 | if (NOT LLVM_ENABLE_RTTI) 152 | target_compile_options(hyde PRIVATE -fno-rtti) 153 | endif() 154 | 155 | target_link_libraries(hyde 156 | clang 157 | clangAST 158 | clangASTMatchers 159 | clangBasic 160 | clangFrontend 161 | clangLex 162 | clangTooling 163 | ) 164 | 165 | if (PROJECT_IS_TOP_LEVEL) 166 | set_target_properties(hyde PROPERTIES XCODE_GENERATE_SCHEME ON) 167 | endif() 168 | -------------------------------------------------------------------------------- /matchers/utilities.hpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | #pragma once 13 | 14 | // stdc++ 15 | #include 16 | 17 | // clang/llvm 18 | // clang-format off 19 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 20 | #include "clang/AST/Attr.h" 21 | #include "clang/AST/Decl.h" 22 | #include "clang/ASTMatchers/ASTMatchFinder.h" 23 | #include "clang/ASTMatchers/ASTMatchers.h" 24 | #include "llvm/ADT/ArrayRef.h" 25 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 26 | // clang-format on 27 | 28 | // application 29 | #include "json.hpp" 30 | #include "matchers/matcher_fwd.hpp" 31 | 32 | /**************************************************************************************************/ 33 | 34 | namespace hyde { 35 | 36 | /**************************************************************************************************/ 37 | 38 | json GetParentNamespaces(const clang::ASTContext* n, const clang::Decl* d); 39 | 40 | json GetParentCXXRecords(const clang::ASTContext* n, const clang::Decl* d); 41 | 42 | json GetTemplateParameters(const clang::ASTContext* n, const clang::TemplateDecl* d); 43 | 44 | optional_json DetailFunctionDecl(const hyde::processing_options& options, 45 | const clang::FunctionDecl* f); 46 | 47 | optional_json DetailCXXRecordDecl(const hyde::processing_options& options, 48 | const clang::CXXRecordDecl* cxx); 49 | 50 | bool PathCheck(const std::vector& paths, const clang::Decl* d, clang::ASTContext* n); 51 | 52 | bool AccessCheck(ToolAccessFilter hyde_filter, clang::AccessSpecifier clang_access); 53 | 54 | bool NamespaceBlacklist(const std::vector& blacklist, const json& j); 55 | 56 | std::string GetArgumentList(const llvm::ArrayRef args); 57 | 58 | std::string ReplaceAll(std::string str, const std::string& substr, const std::string& replacement); 59 | 60 | // type-parameter-N-M filtering. 61 | std::string PostProcessType(const clang::Decl* decl, std::string type); 62 | 63 | // Doxygen-style comments. 64 | optional_json ProcessComments(const clang::Decl* d); 65 | 66 | /**************************************************************************************************/ 67 | 68 | const std::string& hyde_version(); 69 | 70 | /**************************************************************************************************/ 71 | 72 | /// compute a value (based on a diff algorithm) to determine roughly how much two strings are like 73 | /// each other. The lower the value the better, with 0 meaning the two strings are identical. 74 | std::size_t diff_score(std::string_view src, std::string_view dst); 75 | 76 | // Iterate the list of `dst` subfolders, find their `index.md` files, load the `title` of each, and 77 | // find the best-fit against the given `title`. This facilitates the transcription behavior. 78 | std::filesystem::path derive_transcription_src_path(const std::filesystem::path& dst, 79 | const std::string& title); 80 | 81 | /**************************************************************************************************/ 82 | 83 | inline std::string to_string(clang::AccessSpecifier access) { 84 | switch (access) { 85 | case clang::AccessSpecifier::AS_public: 86 | return "public"; 87 | case clang::AccessSpecifier::AS_protected: 88 | return "protected"; 89 | case clang::AccessSpecifier::AS_private: 90 | return "private"; 91 | case clang::AccessSpecifier::AS_none: 92 | return "none"; 93 | } 94 | return "unknown"; 95 | } 96 | 97 | /**************************************************************************************************/ 98 | 99 | inline std::string to_string(const clang::Decl* decl, clang::QualType type) { 100 | static const clang::PrintingPolicy policy(decl->getASTContext().getLangOpts()); 101 | std::string result = PostProcessType(decl, type.getAsString(policy)); 102 | bool is_lambda = result.find("(lambda at ") == 0; 103 | return is_lambda ? "__lambda" : result; 104 | } 105 | 106 | /**************************************************************************************************/ 107 | 108 | template 109 | optional_json StandardDeclInfo(const hyde::processing_options& options, const DeclarationType* d) { 110 | clang::ASTContext* n = &d->getASTContext(); 111 | 112 | if (!PathCheck(options._paths, d, n)) return std::nullopt; 113 | 114 | json info = json::object(); 115 | 116 | info["name"] = d->getNameAsString(); 117 | info["namespaces"] = GetParentNamespaces(n, d); 118 | info["parents"] = GetParentCXXRecords(n, d); 119 | info["qualified_name"] = d->getQualifiedNameAsString(); 120 | 121 | if (NamespaceBlacklist(options._namespace_blacklist, info)) return std::nullopt; 122 | 123 | auto clang_access = d->getAccess(); 124 | 125 | if (!AccessCheck(options._access_filter, clang_access)) return std::nullopt; 126 | 127 | if (auto comments = ProcessComments(d)) { 128 | info["comments"] = std::move(*comments); 129 | } 130 | 131 | if (clang_access != clang::AccessSpecifier::AS_none) info["access"] = to_string(clang_access); 132 | 133 | info["defined_in_file"] = [&] { 134 | auto beginLoc = d->getBeginLoc(); 135 | auto location = beginLoc.printToString(n->getSourceManager()); 136 | return location.substr(0, location.find(':')); 137 | }(); 138 | 139 | info["deprecated"] = false; 140 | 141 | if (auto attr = d->template getAttr()) { 142 | info["deprecated"] = true; 143 | auto message = attr->getMessage(); 144 | info["deprecated_message"] = message.str(); 145 | } 146 | 147 | return info; 148 | } 149 | 150 | /**************************************************************************************************/ 151 | 152 | } // namespace hyde 153 | 154 | /**************************************************************************************************/ 155 | -------------------------------------------------------------------------------- /emitters/yaml_class_emitter.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "yaml_class_emitter.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // application 19 | #include "emitters/yaml_function_emitter.hpp" 20 | #include "matchers/utilities.hpp" 21 | 22 | /**************************************************************************************************/ 23 | 24 | namespace hyde { 25 | 26 | /**************************************************************************************************/ 27 | 28 | bool yaml_class_emitter::do_merge(const std::string& filepath, 29 | const json& have, 30 | const json& expected, 31 | json& out_merged) { 32 | bool failure{false}; 33 | 34 | failure |= check_scalar(filepath, have, expected, "", out_merged, "defined_in_file"); 35 | failure |= check_scalar_array(filepath, have, expected, "", out_merged, "annotation"); 36 | failure |= check_scalar(filepath, have, expected, "", out_merged, "declaration"); 37 | failure |= check_scalar_array(filepath, have, expected, "", out_merged, "namespace"); 38 | failure |= check_scalar(filepath, have, expected, "", out_merged, "ctor"); 39 | failure |= check_scalar(filepath, have, expected, "", out_merged, "dtor"); 40 | failure |= check_map( 41 | filepath, have, expected, "", out_merged, "fields", 42 | [this](const std::string& filepath, const json& have, const json& expected, 43 | const std::string& nodepath, json& out_merged) { 44 | bool failure{false}; 45 | 46 | failure |= check_scalar(filepath, have, expected, nodepath, out_merged, "type"); 47 | failure |= check_editable_scalar(filepath, have, expected, nodepath, out_merged, 48 | "description"); 49 | failure |= 50 | check_scalar_array(filepath, have, expected, nodepath, out_merged, "annotation"); 51 | 52 | check_inline_comments(expected, out_merged); 53 | 54 | return failure; 55 | }); 56 | 57 | failure |= check_typedefs(filepath, have, expected, "", out_merged); 58 | 59 | failure |= check_object_array( 60 | filepath, have, expected, "", out_merged, "methods", "title", 61 | [this](const std::string& filepath, const json& have, const json& expected, 62 | const std::string& nodepath, json& out_merged) { 63 | yaml_function_emitter function_emitter(_src_root, _dst_root, _mode, _options, true); 64 | return function_emitter.do_merge(filepath, have, expected, out_merged); 65 | }); 66 | 67 | check_inline_comments(expected, out_merged); 68 | 69 | return failure; 70 | } 71 | 72 | /**************************************************************************************************/ 73 | 74 | bool yaml_class_emitter::emit(const json& j, json& out_emitted, const json& inherited) { 75 | json node = base_emitter_node("class", j["name"], "class", has_json_flag(j, "implicit")); 76 | node["hyde"]["defined_in_file"] = defined_in_file(j["defined_in_file"], _src_root); 77 | 78 | insert_inherited(inherited, node["hyde"]); 79 | insert_annotations(j, node["hyde"]); 80 | insert_doxygen(j, node["hyde"]); 81 | 82 | std::string declaration = format_template_parameters(j, true) + '\n' + 83 | static_cast(j["kind"]) + " " + 84 | static_cast(j["qualified_name"]) + ";"; 85 | node["hyde"]["declaration"] = std::move(declaration); 86 | 87 | for (const auto& ns : j["namespaces"]) 88 | node["hyde"]["namespace"].push_back(static_cast(ns)); 89 | 90 | if (j.count("ctor")) node["hyde"]["ctor"] = static_cast(j["ctor"]); 91 | if (j.count("dtor")) node["hyde"]["dtor"] = static_cast(j["dtor"]); 92 | 93 | if (j.count("fields")) { 94 | for (const auto& field : j["fields"]) { 95 | const std::string& key = field["name"]; 96 | auto& field_node = node["hyde"]["fields"][key]; 97 | insert_annotations(field, field_node); 98 | insert_doxygen(field, field_node); 99 | 100 | field_node["type"] = static_cast(field["type"]); 101 | const bool inline_description_exists = 102 | field_node.count("inline") && field_node["inline"].count("description"); 103 | field_node["description"] = 104 | inline_description_exists ? tag_value_inlined_k : tag_value_missing_k; 105 | } 106 | } 107 | 108 | insert_typedefs(j, node, inherited); 109 | 110 | auto dst = dst_path(j, static_cast(j["name"])); 111 | 112 | if (_mode == yaml_mode::transcribe && !exists(dst)) { 113 | // In this case the symbol name has changed, which has caused a change to the directory name 114 | // we are now trying to load and reconcile with what we've created. In this case, we can 115 | // assume the "shape" of the documentation is the same, which means that within the parent 116 | // folder of `dst` is the actual source folder that holds the old documentation, just under 117 | // a different name. Find that folder and rename it. 118 | 119 | std::filesystem::rename(derive_transcription_src_path(dst, node["title"]), dst); 120 | } 121 | 122 | bool failure = 123 | reconcile(std::move(node), _dst_root, std::move(dst) / index_filename_k, out_emitted); 124 | 125 | yaml_function_emitter function_emitter(_src_root, _dst_root, _mode, _options, true); 126 | auto emitted_methods = hyde::json::array(); 127 | const auto& methods = j["methods"]; 128 | 129 | for (auto it = methods.begin(); it != methods.end(); ++it) { 130 | function_emitter.set_key(it.key()); 131 | auto function_emitted = hyde::json::object(); 132 | failure |= function_emitter.emit(it.value(), function_emitted, out_emitted.at("hyde")); 133 | emitted_methods.push_back(std::move(function_emitted)); 134 | } 135 | 136 | out_emitted["methods"] = std::move(emitted_methods); 137 | 138 | return failure; 139 | } 140 | 141 | /**************************************************************************************************/ 142 | 143 | } // namespace hyde 144 | 145 | /**************************************************************************************************/ 146 | -------------------------------------------------------------------------------- /sources/autodetect.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "autodetect.hpp" 14 | 15 | // stdc++ 16 | #include 17 | #include 18 | #include 19 | #include 20 | #include 21 | #include 22 | #include 23 | #include 24 | #include 25 | #include 26 | 27 | /**************************************************************************************************/ 28 | 29 | namespace { 30 | 31 | /**************************************************************************************************/ 32 | 33 | std::vector split(const char* p, std::size_t n) { 34 | auto end = p + n; 35 | std::vector result; 36 | 37 | while (p != end) { 38 | while (p != end && *p == '\n') 39 | ++p; // eat newlines 40 | auto begin = p; 41 | while (p != end && *p != '\n') 42 | ++p; // eat non-newlines 43 | result.emplace_back(begin, p); 44 | } 45 | 46 | return result; 47 | } 48 | 49 | /**************************************************************************************************/ 50 | 51 | std::vector file_slurp(std::filesystem::path p) { 52 | std::ifstream s(p); 53 | s.seekg(0, std::ios::end); 54 | std::size_t size = s.tellg(); 55 | auto buffer{std::make_unique(size)}; 56 | s.seekg(0); 57 | s.read(&buffer[0], size); 58 | return split(buffer.get(), size); 59 | } 60 | 61 | /**************************************************************************************************/ 62 | 63 | std::string trim_front(std::string s) { 64 | std::size_t n(0); 65 | std::size_t end(s.size()); 66 | 67 | while (n != end && (std::isspace(s[n]) || s[n] == '\n')) 68 | ++n; 69 | 70 | s.erase(0, n); 71 | 72 | return s; 73 | } 74 | 75 | /**************************************************************************************************/ 76 | 77 | std::string trim_back(std::string s) { 78 | std::size_t start(s.size()); 79 | 80 | while (start != 0 && (std::isspace(s[start - 1]) || s[start - 1] == '\n')) 81 | start--; 82 | 83 | s.erase(start, std::string::npos); 84 | 85 | return s; 86 | } 87 | 88 | /**************************************************************************************************/ 89 | 90 | std::string chomp(std::string src) { return trim_back(trim_front(std::move(src))); } 91 | 92 | /**************************************************************************************************/ 93 | 94 | std::string exec(const char* cmd) { 95 | struct pclose_t { 96 | void operator()(std::FILE* p) const { (void)pclose(p); } 97 | }; 98 | std::unique_ptr pipe{popen(cmd, "r")}; 99 | 100 | if (!pipe) { 101 | throw std::runtime_error("popen() failed!"); 102 | } 103 | 104 | std::array buffer; 105 | std::string result; 106 | while (fgets(buffer.data(), buffer.size(), pipe.get())) { 107 | result += buffer.data(); 108 | } 109 | 110 | return chomp(std::move(result)); 111 | } 112 | 113 | /**************************************************************************************************/ 114 | 115 | std::vector autodetect_include_paths() { 116 | // Add a random value here so two concurrent instances of hyde don't collide. 117 | auto v = std::to_string(std::mt19937(std::random_device()())()); 118 | auto temp_dir = std::filesystem::temp_directory_path(); 119 | auto temp_out = (temp_dir / ("hyde_" + v + ".tmp")).string(); 120 | auto temp_a_out = (temp_dir / ("deleteme_" + v)).string(); 121 | auto command = 122 | "echo \"int main() { }\" | clang++ -x c++ -v -o " + temp_a_out + " - 2> " + temp_out; 123 | 124 | auto command_result = std::system(command.c_str()); 125 | (void)command_result; // TODO: handle me 126 | 127 | std::vector lines(file_slurp(temp_out)); 128 | static const std::string begin_string("#include <...> search starts here:"); 129 | static const std::string end_string("End of search list."); 130 | auto paths_begin = std::find(begin(lines), end(lines), begin_string); 131 | auto paths_end = std::find(begin(lines), end(lines), end_string); 132 | std::vector result; 133 | 134 | if (paths_begin != end(lines) && paths_end != end(lines)) { 135 | lines.erase(paths_end, end(lines)); 136 | lines.erase(begin(lines), std::next(paths_begin)); 137 | 138 | // lines.erase(std::remove_if(begin(lines), end(lines), [](auto& s){ 139 | // return s.find(".sdk/") != std::string::npos; 140 | // }), end(lines)); 141 | 142 | // Some of the paths contain cruft at the end. Filter those out, too. 143 | std::transform(begin(lines), end(lines), std::back_inserter(result), [](auto s) { 144 | static const std::string needle_k{" (framework directory)"}; 145 | auto needle_pos = s.find(needle_k); 146 | if (needle_pos != std::string::npos) { 147 | s.erase(needle_pos); 148 | } 149 | return std::filesystem::path(chomp(std::move(s))); 150 | }); 151 | } 152 | 153 | return result; 154 | } 155 | 156 | /**************************************************************************************************/ 157 | 158 | } // namespace 159 | 160 | /**************************************************************************************************/ 161 | 162 | namespace hyde { 163 | 164 | /**************************************************************************************************/ 165 | 166 | std::vector autodetect_toolchain_paths() { 167 | return autodetect_include_paths(); 168 | } 169 | 170 | /**************************************************************************************************/ 171 | 172 | std::filesystem::path autodetect_resource_directory() { 173 | return std::filesystem::path{exec("clang++ -print-resource-dir")}; 174 | } 175 | 176 | /**************************************************************************************************/ 177 | #if HYDE_PLATFORM(APPLE) 178 | std::filesystem::path autodetect_sysroot_directory() { 179 | return std::filesystem::path{exec("xcode-select -p")} / 180 | "Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk"; 181 | } 182 | #endif // HYDE_PLATFORM(APPLE) 183 | /**************************************************************************************************/ 184 | 185 | } // namespace hyde 186 | 187 | /**************************************************************************************************/ 188 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # What is `hyde` 2 | 3 | `hyde` is a utility that facilitates documenting C++. The tool is unique from existing documentation utilities in the following ways: 4 | 5 | - **Clang based**: In order to properly document your C++, `hyde` compiles it using Clang's excellent [libTooling](https://clang.llvm.org/docs/LibTooling.html) library. Therefore, as the C++ language evolves, so too will `hyde`. 6 | - **Out-of-line**: Many tools rely on documentation placed inline within source as long-form comments. While these seem appealing at first blush, they suffer from two big drawbacks. First, there is nothing keeping the comments from falling out of sync from the elements they document. Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code with comments they no longer read. 7 | - **Jekyll compatible**: `hyde` does not produce pretty-printed output. Rather, it produces well structured Markdown files that contain YAML front-matter. These files can then be consumed by other tools (like Jekyll) to customize the structure and layout of the final documentation. 8 | - **Schema enforcement**: Because of the highly structured nature of the output, `hyde` is able to compare pre-existing documentation files against the current state of your C++ sources. Library developers can use `hyde`'s _update_ mode to facilitate updating documentation against the state of sources. Build engineers can use `hyde`'s _validate_ mode to make sure changes to a code base are accurately reflected in the latest documentation. In the end, the documentation stays true to the code with minimal effort. 9 | - **Adaptable**: While `hyde`'s primary purpose at this point is to output and enforce documentation, the tool can also be used to output AST-based information about your code as a JSON-based IR. This makes room for additional tools to be build atop what `hyde` is able to produce, or additional emitters can be added natively to the tool. 10 | 11 | # Example Output 12 | 13 | `hyde` produces intermediate documentation files that the developer then fills in with additional details as necessary. The files are then fed through a static site generation tool (like Jekyll) to produce [output like this](https://stlab.cc/includes/stlab/copy_on_write.hpp/copy_on_write3CT3E/). 14 | 15 | # Requirements 16 | 17 | ## macOS 18 | 19 | - Homebrew 20 | - `brew install cmake` 21 | - `brew install ninja` (optional) 22 | 23 | ## Linux 24 | 25 | (Note: only tested on ubuntu bionic so far) 26 | 27 | - Apt 28 | - `sudo apt-get install libyaml-cpp-dev` 29 | 30 | # How to Build 31 | 32 | - clone this repo 33 | - `cd hyde` 34 | - `git submodule update --init` 35 | - `mkdir build` 36 | - `cd build` 37 | - `cmake .. -GNinja` (or `-GXcode`, etc.) 38 | - `ninja` (or whatever your IDE does) 39 | 40 | LLVM/Clang are declared as a dependency in the project's `CMakeLists.txt` file, and will be downloaded and made available to the project automatically. 41 | 42 | # How to run from Docker 43 | 44 | ```sh 45 | docker pull ghcr.io/adobe/hyde:latest 46 | 47 | docker run --platform linux/x86_64 --mount type=bind,source="$(pwd)",target=/mnt/host \ 48 | --tty --interactive \ 49 | ghcr.io/adobe/hyde:latest bash 50 | ``` 51 | 52 | You can then run the examples as below, except don't prefix `hyde` with `./`. 53 | 54 | # Building the Docker image 55 | 56 | You may need to increase your docker resources to build the image. (2.0.1 successfully built with 16GB RAM and 4GB swap) 57 | 58 | ```sh 59 | docker build --tag hyde . 60 | 61 | docker run --platform linux/x86_64 --mount type=bind,source="$(pwd)",target=/mnt/host \ 62 | --tty --interactive \ 63 | hyde bash 64 | ``` 65 | 66 | # Publishing the docker image (requires write access to the `adobe` GitHub organization) 67 | 68 | Instructions for publishing a GitHub package can be found [here](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry). 69 | Instructions for associating the with the `adobe/hyde` repository can be found [here](https://docs.github.com/en/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-a-container-image-using-the-command-line). 70 | 71 | ```sh 72 | VERSION=2.0.1 73 | docker tag hyde ghcr.io/adobe/hyde:$VERSION 74 | docker tag hyde ghcr.io/adobe/hyde:latest 75 | docker push ghcr.io/adobe/hyde:$VERSION 76 | docker push ghcr.io/adobe/hyde:latest 77 | ``` 78 | 79 | 80 | # Parameters and Flags 81 | 82 | There are several modes under which the tool can run: 83 | 84 | - `-hyde-json` - (default) Output an analysis dump of the input file as JSON 85 | - `-hyde-validate` - Validate existing YAML documentation 86 | - `-hyde-update` - Write updated YAML documentation 87 | 88 | - `-hyde-src-root = ` - The root path to the header file(s) being analyzed. Affects `defined_in_file` output values by taking out the root path. 89 | - `-hyde-yaml-dir = ` - Root directory for YAML validation / update. Required for either hyde-validate or hyde-update modes. 90 | 91 | - `--use-system-clang` - Autodetect and use necessary resource directories and include paths 92 | 93 | - `--fixup-hyde-subfield` - As of Hyde v0.1.5, all hyde fields are under a top-level `hyde` subfield in YAML output. This flag will update older hyde documentation that does not have this subfield by creating it, then moving all top-level fields except `title` and `layout` under it. This flag is intended to be used only once during the migration of older documentation from the non-subfield structure to the subfield structure. 94 | 95 | This tool parses the passed header using Clang. To pass arguments to the compiler (e.g., include directories), append them after the `--` token on the command line. For example: 96 | 97 | hyde input_file.hpp -hyde-json -use-system-clang -- -x c++ -I/path/to/includes 98 | 99 | Alternatively, if you have a compilation database and would like to pass that instead of command-line compiler arguments, you can pass that with `-p`. 100 | 101 | While compiling the source file, the non-function macro `ADOBE_TOOL_HYDE` is defined to the value `1`. This can be useful to explicitly omit code from the documentation. 102 | 103 | # Examples: 104 | 105 | To output JSON: 106 | ```./hyde -use-system-clang ../test_files/classes.cpp --``` 107 | 108 | To validate pre-existing YAML: 109 | ```./hyde -use-system-clang -hyde-yaml-dir=/path/to/output -hyde-validate ../test_files/classes.cpp``` 110 | 111 | To output updated YAML: 112 | ```./hyde -use-system-clang -hyde-yaml-dir=/path/to/output -hyde-update ../test_files/classes.cpp``` 113 | 114 | # Hyde 1 to Hyde 2 Format Conversion 115 | 116 | As of the Hyde 2 work, all subfields in the YAML output (except the Jekyll-required `layout` and `title` fields) must go under a top-level `hyde` subfield. This allows for other tools to include additional (possibly same-named) fields under their own top-level subfields in the YAML. 117 | 118 | Here is an example of updating from Hyde 1 to Hyde 2 formatted docs by scanning a directory for markdown-formatted files and passing them to `hyde` with the new `-hyde-fixup-subfield` mode: 119 | 120 | find . -name '*.md' | xargs -I % -L 1 /path/to/hyde -hyde-fixup-subfield % -- 121 | 122 | # Sass Updates 123 | 124 | Sometimes it may be necessary to clean up or "lint" the sass files. You can do so with: 125 | 126 | bundle exec sass-convert -i /path/to/file.scss 127 | -------------------------------------------------------------------------------- /test_files/classes.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // AST dump with 13 | // clang --std=c++1z -Xclang -ast-dump -fsyntax-only ./test_files/classes.cpp 14 | 15 | #include 16 | #include 17 | 18 | //------------------------------------------------------------------------------------------------------------------------------------------ 19 | 20 | /// @brief an example class that demonstrates what Hyde documents. 21 | /// @hyde-owner fosterbrereton 22 | class class_example { 23 | public: 24 | /// Note that nested classes will not inherit their ownership from 25 | /// the class that contains them, so thus need their own `hyde-owner`. 26 | /// @brief an example enumeration within the class. 27 | /// @hyde-owner sean-parent 28 | enum class color { 29 | /// this is an example description for the `red` value. 30 | red, 31 | /// this is an example description for the `green` value. 32 | green = 42, 33 | /// this is an example description for the `blue` value. 34 | blue 35 | }; 36 | 37 | /// Note that nested classes will not inherit their ownership from 38 | /// the class that contains them, so thus need their own `hyde-owner`. 39 | /// @brief a class definition contained within `example_class`. 40 | /// @hyde-owner sean-parent 41 | struct nested_class_example { 42 | /// member field `_x` within the nested class example. 43 | int _x{0}; 44 | 45 | /// member field `_y` within the nested class example. 46 | int _y; 47 | }; 48 | 49 | 50 | /// a nested `typedef` expression. 51 | typedef std::string typedef_example; 52 | 53 | /// a nested `using` expression. 54 | using using_example = std::string; 55 | 56 | 57 | /// default constructor. 58 | class_example() = default; 59 | 60 | /// an explicit constructor that takes a single `int`. 61 | /// @param x The one integer parameter this routine takes 62 | explicit class_example(int x) : _x(x) {} 63 | 64 | 65 | /// member function with a trailing return type. 66 | /// @return "`_x`" 67 | auto member_function_trailing_return_type() const -> int { return _x; } 68 | 69 | /// example member function. 70 | /// @return double the value of `_x`. 71 | auto member_function() { return _x *= 2; } 72 | 73 | 74 | /// an overloaded member function that takes one parameter. 75 | /// @brief A series of overloaded functions. 76 | /// @param first the first parameter of the first overload. 77 | void overloaded(const std::string& first); 78 | 79 | /// an overloaded member function that takes two parameters. 80 | /// @brief Another brief describing one of the overloaded functions. 81 | /// @param first the first parameter of the second overload. 82 | /// @param second the second parameter of the second overload. 83 | void overloaded(const std::string& first, const std::string& second) volatile; 84 | 85 | /// another overloaded member function that takes two parameters. 86 | /// @param first the first parameter of the third overload. 87 | /// @param second the second parameter of the third overload. 88 | void overloaded(const std::string& first, std::vector second) const; 89 | 90 | /// an overloaded member function that takes _five_ parameters. 91 | /// @param first the first parameter of the fourth overload. 92 | /// @param second the second parameter of the fourth overload. 93 | /// @param third the third parameter of the fourth overload. 94 | /// @param fourth the fourth parameter of the fourth overload. 95 | /// @param fifth the fifth parameter of the fourth overload. 96 | void overloaded( 97 | const std::string& first, class_example* second, int third, bool fourth, std::size_t fifth); 98 | 99 | /// an overloaded member function that takes three unnamed parameters. 100 | /// Let it be known that Doxygen doesn't support documenting unnamed parameters at this time. 101 | /// There is a [bug open on the issue](https://github.com/doxygen/doxygen/issues/6926), but as 102 | /// of this writing does not appear to be progressing. 103 | void overloaded(const std::string&, class_example*, int); // intentionally unnamed 104 | 105 | /// a deprecated overload that takes zero parameters. 106 | [[deprecated]] void overloaded(); 107 | 108 | 109 | /// deprecated member function. 110 | /// @param first the first parameter 111 | /// @param second the second parameter 112 | [[deprecated]] void deprecated(const std::string& first, class_example* second); 113 | 114 | /// deprecated member function that contains a compile-time deprecation message. 115 | /// @param s the first parameter 116 | /// @param f the second parameter 117 | [[deprecated("example deprecation message")]] void deprecated_with_message(const std::string& s, class_example* f); 118 | 119 | /// static member variable. 120 | static const int _static_member = 0; 121 | 122 | /// @brief static member function. 123 | /// @return Zero. 124 | // By which I mean `0`. 125 | // In the sources, this comment is on multiple lines. 126 | static int static_method() { return 0; }; 127 | 128 | /// templatized member function. 129 | template 130 | void template_member_function() {} 131 | 132 | /// specialization of the above templatized member function. 133 | template <> 134 | void template_member_function() {} 135 | 136 | private: 137 | /// some variable that holds an integer. 138 | int _x; 139 | 140 | /// a deprecated member variable that contains a message. Apparently this works?! 141 | [[deprecated("example deprecation message")]] int _deprecated_member = 0; 142 | 143 | /// an instance of the nested class example defined earlier. 144 | nested_class_example _nested; 145 | }; 146 | 147 | //------------------------------------------------------------------------------------------------------------------------------------------ 148 | 149 | /// @brief an example template class with some specializations 150 | /// @hyde-owner fosterbrereton 151 | template 152 | struct specialization_example { 153 | constexpr auto as_tuple() const { return std::forward_as_tuple(); } 154 | }; 155 | 156 | /// @brief an example `std::int32` specialization 157 | /// @hyde-owner fosterbrereton 158 | template <> 159 | struct specialization_example { 160 | /// An example typedef 161 | using value_type = std::int32_t; 162 | value_type _first{0}; ///< An example field used in `as_tuple` 163 | /// An example function 164 | /// @return a tuple of the fields of this class 165 | constexpr auto as_tuple() const { return std::forward_as_tuple(_first); } 166 | }; 167 | 168 | /// @brief an example `float` specialization 169 | /// @hyde-owner fosterbrereton 170 | template <> 171 | struct specialization_example { 172 | using value_type = float; ///< An example typedef 173 | value_type _first{0}; ///< An example field used in `as_tuple` 174 | constexpr auto as_tuple() const { return std::forward_as_tuple(_first); } 175 | }; 176 | 177 | //------------------------------------------------------------------------------------------------------------------------------------------ 178 | 179 | /// @brief an example template class with a partial specialization. 180 | /// @hyde-owner fosterbrereton 181 | template 182 | class partial_specialization_example { 183 | T1 _first; 184 | T2 _second; 185 | }; 186 | 187 | /// @brief an example `int, T` partial specialization 188 | /// @hyde-owner fosterbrereton 189 | template 190 | class partial_specialization_example { 191 | std::string _first; 192 | T _second; 193 | }; 194 | 195 | //------------------------------------------------------------------------------------------------------------------------------------------ 196 | -------------------------------------------------------------------------------- /matchers/class_matcher.cpp: -------------------------------------------------------------------------------- 1 | /* 2 | Copyright 2018 Adobe 3 | All Rights Reserved. 4 | 5 | NOTICE: Adobe permits you to use, modify, and distribute this file in 6 | accordance with the terms of the Adobe license agreement accompanying 7 | it. If you have received this file from a source other than Adobe, 8 | then your use, modification, or distribution of it requires the prior 9 | written permission of Adobe. 10 | */ 11 | 12 | // identity 13 | #include "class_matcher.hpp" 14 | 15 | // stdc++ 16 | #include 17 | 18 | // clang/llvm 19 | // clang-format off 20 | #include "_clang_include_prefix.hpp" // must be first to disable warnings for clang headers 21 | #include "clang/AST/ASTConsumer.h" 22 | #include "clang/AST/RecursiveASTVisitor.h" 23 | #include "clang/ASTMatchers/ASTMatchFinder.h" 24 | #include "clang/ASTMatchers/ASTMatchers.h" 25 | #include "_clang_include_suffix.hpp" // must be last to re-enable warnings 26 | // clang-format on 27 | 28 | // application 29 | #include "json.hpp" 30 | #include "matchers/utilities.hpp" 31 | 32 | using namespace clang; 33 | using namespace clang::ast_matchers; 34 | 35 | /**************************************************************************************************/ 36 | 37 | class FindDestructor : public RecursiveASTVisitor { 38 | public: 39 | bool VisitDecl(const Decl* d) { 40 | if (isa(d)) _found = true; 41 | return !_found; 42 | } 43 | 44 | explicit operator bool() const { return _found; } 45 | 46 | private: 47 | bool _found{false}; 48 | }; 49 | 50 | /**************************************************************************************************/ 51 | 52 | class FindConstructor : public RecursiveASTVisitor { 53 | public: 54 | bool VisitDecl(const Decl* d) { 55 | if (isa(d)) _found = true; 56 | return !_found; 57 | } 58 | 59 | explicit operator bool() const { return _found; } 60 | 61 | private: 62 | bool _found{false}; 63 | }; 64 | 65 | /**************************************************************************************************/ 66 | 67 | class FindStaticMembers : public RecursiveASTVisitor { 68 | public: 69 | FindStaticMembers(const hyde::processing_options& options) 70 | : _options(options), _static_members(hyde::json::object()) {} 71 | bool VisitVarDecl(const VarDecl* d) { 72 | if (!AccessCheck(_options._access_filter, d->getAccess())) return true; 73 | 74 | auto storage = d->getStorageClass(); 75 | // TODO(Wyles): Do we want to worry about other kinds of storage? 76 | if (storage == SC_Static) { 77 | auto type_opt = hyde::StandardDeclInfo(_options, d); 78 | if (!type_opt) return true; 79 | auto type = std::move(*type_opt); 80 | auto name = type["qualified_name"].get(); 81 | type["static"] = true; 82 | type["type"] = hyde::to_string(d, d->getType()); 83 | _static_members[name] = type; 84 | } 85 | return true; 86 | } 87 | 88 | const hyde::json& get_results() const { return _static_members; } 89 | 90 | private: 91 | const hyde::processing_options& _options; 92 | hyde::json _static_members; 93 | }; 94 | 95 | namespace hyde { 96 | 97 | /**************************************************************************************************/ 98 | 99 | json fixup_short_name(json&& method) { 100 | // We have encountered cases with the latest clang drivers where the short_name field for some 101 | // methods is missing. In such case we try to cobble up a solution by finding the 102 | // first sequence of alphanumeric characters after the return type. If _that_ doesn't work, 103 | // then we fall back on the signature name. 104 | if (method.count("short_name") && 105 | method.at("short_name").is_string() && 106 | !static_cast(method.at("short_name")).empty()) { 107 | return std::move(method); 108 | } 109 | 110 | std::string short_name = method["signature"]; 111 | 112 | if (method.count("return_type") && method["return_type"].is_string() && 113 | method.count("signature") && method["signature"].is_string()) { 114 | const std::string& return_type = method["return_type"]; 115 | const std::string& signature = method["signature"]; 116 | const auto offset = signature.find(return_type); 117 | if (offset != std::string::npos) { 118 | const auto start = offset + return_type.size() + 1; 119 | const auto end = signature.find_first_of("(", start); 120 | short_name = signature.substr(start, end - start); 121 | 122 | } 123 | } 124 | 125 | method["short_name"] = std::move(short_name); 126 | 127 | return std::move(method); 128 | } 129 | 130 | /**************************************************************************************************/ 131 | 132 | void ClassInfo::run(const MatchFinder::MatchResult& Result) { 133 | auto clas = Result.Nodes.getNodeAs("class"); 134 | 135 | if (!clas->isCompleteDefinition()) return; // e.g., a forward declaration. 136 | 137 | if (clas->isLambda()) return; 138 | 139 | if (!clas->getSourceRange().isValid()) return; // e.g., compiler-injected class specialization 140 | 141 | // e.g., compiler-injected class specializations not caught by the above 142 | if (auto s = llvm::dyn_cast_or_null(clas)) { 143 | if (!s->getTypeAsWritten()) return; 144 | } 145 | 146 | auto info_opt = DetailCXXRecordDecl(_options, clas); 147 | if (!info_opt) return; 148 | auto info = std::move(*info_opt); 149 | 150 | if (NamespaceBlacklist(_options._namespace_blacklist, info)) return; 151 | 152 | info["kind"] = clas->getKindName(); 153 | info["methods"] = json::object(); 154 | 155 | FindConstructor ctor_finder; 156 | ctor_finder.TraverseDecl(const_cast(static_cast(clas))); 157 | if (!ctor_finder) info["ctor"] = "unspecified"; 158 | 159 | FindDestructor dtor_finder; 160 | dtor_finder.TraverseDecl(const_cast(static_cast(clas))); 161 | if (!dtor_finder) info["dtor"] = "unspecified"; 162 | 163 | FindStaticMembers static_finder(_options); 164 | static_finder.TraverseDecl(const_cast(static_cast(clas))); 165 | 166 | if (const auto& template_decl = clas->getDescribedClassTemplate()) { 167 | info["template_parameters"] = GetTemplateParameters(Result.Context, template_decl); 168 | } 169 | 170 | for (const auto& method : clas->methods()) { 171 | auto methodInfo_opt = DetailFunctionDecl(_options, method); 172 | if (!methodInfo_opt) continue; 173 | auto methodInfo = std::move(*methodInfo_opt); 174 | methodInfo = fixup_short_name(std::move(methodInfo)); 175 | const auto& short_name = static_cast(methodInfo["short_name"]); 176 | info["methods"][short_name].push_back(std::move(methodInfo)); 177 | } 178 | 179 | for (const auto& decl : clas->decls()) { 180 | auto* function_template_decl = dyn_cast(decl); 181 | if (!function_template_decl) continue; 182 | auto methodInfo_opt = 183 | DetailFunctionDecl(_options, function_template_decl->getTemplatedDecl()); 184 | if (!methodInfo_opt) continue; 185 | auto methodInfo = std::move(*methodInfo_opt); 186 | methodInfo = fixup_short_name(std::move(methodInfo)); 187 | const auto& short_name = static_cast(methodInfo["short_name"]); 188 | info["methods"][short_name].push_back(std::move(methodInfo)); 189 | } 190 | 191 | for (const auto& field : clas->fields()) { 192 | auto fieldInfo_opt = StandardDeclInfo(_options, field); 193 | if (!fieldInfo_opt) continue; 194 | auto fieldInfo = std::move(*fieldInfo_opt); 195 | fieldInfo["type"] = hyde::to_string(field, field->getType()); 196 | info["fields"][static_cast(fieldInfo["qualified_name"])] = 197 | fieldInfo; // can't move this into place for some reason. 198 | } 199 | 200 | hyde::json static_members = static_finder.get_results(); 201 | 202 | if (static_members.size() > 0) { 203 | if (info["fields"].size() == 0) { 204 | info["fields"] = hyde::json::object(); 205 | } 206 | info["fields"].insert(static_members.begin(), static_members.end()); 207 | } 208 | 209 | using typedef_iterator = CXXRecordDecl::specific_decl_iterator; 210 | using typedef_range = llvm::iterator_range; 211 | typedef_range typedefs(typedef_iterator(clas->decls_begin()), 212 | typedef_iterator(CXXRecordDecl::decl_iterator())); 213 | for (const auto& type_def : typedefs) { 214 | // REVISIT (fbrereto) : Refactor this block and TypedefInfo::run's. 215 | auto typedefInfo_opt = StandardDeclInfo(_options, type_def); 216 | if (!typedefInfo_opt) continue; 217 | auto typedefInfo = std::move(*typedefInfo_opt); 218 | 219 | typedefInfo["type"] = hyde::to_string(type_def, type_def->getUnderlyingType()); 220 | 221 | info["typedefs"].push_back(std::move(typedefInfo)); 222 | } 223 | 224 | using typealias_iterator = CXXRecordDecl::specific_decl_iterator; 225 | using typealias_range = llvm::iterator_range; 226 | typealias_range typealiases(typealias_iterator(clas->decls_begin()), 227 | typealias_iterator(CXXRecordDecl::decl_iterator())); 228 | for (const auto& type_alias : typealiases) { 229 | // REVISIT (fbrereto) : Refactor this block and TypeAliasInfo::run's. 230 | auto typealiasInfo_opt = StandardDeclInfo(_options, type_alias); 231 | if (!typealiasInfo_opt) continue; 232 | auto typealiasInfo = std::move(*typealiasInfo_opt); 233 | 234 | typealiasInfo["type"] = hyde::to_string(type_alias, type_alias->getUnderlyingType()); 235 | if (auto template_decl = type_alias->getDescribedAliasTemplate()) { 236 | typealiasInfo["template_parameters"] = 237 | GetTemplateParameters(Result.Context, template_decl); 238 | } 239 | 240 | info["typealiases"].push_back(std::move(typealiasInfo)); 241 | } 242 | 243 | _j["classes"].push_back(std::move(info)); 244 | } 245 | 246 | /**************************************************************************************************/ 247 | 248 | } // namespace hyde 249 | 250 | /**************************************************************************************************/ 251 | --------------------------------------------------------------------------------