Skip to content

Commit 2047011

Browse files
fosterbreretonfosterbrereton
committed
initial commit
1 parent 055ae2b commit 2047011

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

77 files changed

+22919
-1
lines changed

‎.clang-format

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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+
...

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.vscode/
2+
build/
3+
test_files_out/

‎CMakeLists.txt

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
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+
11+
cmake_minimum_required(VERSION 3.12)
12+
13+
project(hyde)
14+
set(CMAKE_CXX_EXTENSIONS OFF)
15+
set(CMAKE_CXX_STANDARD 17)
16+
set(CMAKE_CXX_STANDARD_REQUIRED ON)
17+
18+
# Change these if you have a different location.
19+
set(BOOST_DIR /usr/local/Cellar/boost/1.67.0_1/)
20+
set(Clang_DIR /usr/local/Cellar/llvm/7.0.0/lib/cmake/clang/)
21+
set(LLVM_DIR /usr/local/Cellar/llvm/7.0.0/lib/cmake/llvm/)
22+
set(YAML_CPP_DIR /usr/local/Cellar/yaml-cpp/0.6.2/lib/cmake/yaml-cpp/)
23+
24+
find_package(Clang REQUIRED clangTooling libClang clangASTMatchers)
25+
find_package(Clang REQUIRED CONFIG)
26+
find_package(LLVM REQUIRED CONFIG)
27+
find_package(YAML-CPP REQUIRED CONFIG)
28+
29+
find_package(Boost COMPONENTS system filesystem REQUIRED)
30+
31+
add_definitions(${Clang_DEFINITIONS})
32+
add_definitions(${LLVM_DEFINITIONS})
33+
add_definitions(${YAML_CPP_DEFINITIONS})
34+
add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})
35+
36+
37+
file(GLOB EMITTER_FILES CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/emitters/*.cpp)
38+
file(GLOB MATCHER_FILES CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/matchers/*.cpp)
39+
file(GLOB SRC_FILES CONFIGURE_DEPENDS ${PROJECT_SOURCE_DIR}/sources/*.cpp)
40+
41+
#TODO: use target_source
42+
add_executable(hyde ${EMITTER_FILES} ${MATCHER_FILES} ${SRC_FILES})
43+
44+
45+
target_include_directories(hyde PUBLIC ${Boost_INCLUDE_DIRS})
46+
target_include_directories(hyde PUBLIC ${CLANG_INCLUDE_DIRS})
47+
target_include_directories(hyde PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
48+
target_include_directories(hyde PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
49+
target_include_directories(hyde PUBLIC ${LLVM_INCLUDE_DIRS})
50+
target_include_directories(hyde PUBLIC ${YAML_CPP_INCLUDE_DIR})
51+
52+
target_link_libraries(hyde
53+
${YAML_CPP_LIBRARIES}
54+
${Boost_FILESYSTEM_LIBRARY}
55+
${Boost_SYSTEM_LIBRARY}
56+
clangASTMatchers
57+
clangBasic
58+
clangTooling
59+
)

‎CODE_OF_CONDUCT.md

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
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 [email protected]. 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/

‎CONTRIBUTING.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
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+
[[email protected]](mailto:[email protected]).
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)

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2018 Adobe Systems Incorporated
3+
© Copyright 2018 Adobe. All rights reserved.
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# What is hyde
2+
3+
The primary goal of hyde for the photoshop team was a way to generate documentation from our current C++ source code, in such a way that can be consumed by jekyll to create static standalone documentation site. The project was born out of what we felt was a limitation or difference of opinion in the approach existing documention tooling. That often requires you to litter your source with inline comments that detracts from readability. These comments also tend to become out of date over time unless you are hyper-vigilant. Hyde can detect this and be used to prevent merging code that doesn't update the documentation.
4+
5+
Whilst the project was built around this use case, care has been taken to create a tool that is adaptable. You can build more tooling on top of the json format that we turn the clang ast into, or you can simply write your own emitter to massage the output into something that will suit your needs.
6+
7+
8+
# Requirements
9+
10+
- Homebrew
11+
- `brew install cmake`
12+
- `brew install llvm`
13+
- `brew install yaml-cpp`
14+
- `brew install boost`
15+
- `brew install ninja` (optional)
16+
17+
# How to Build
18+
19+
- clone this repo
20+
- `cd hyde`
21+
- `mkdir build`
22+
- `cd build`
23+
- `cmake .. -GNinja` (or `-GXcode`, etc.)
24+
- `ninja` (or whatever your IDE does)
25+
26+
# Parameters and Flags
27+
28+
There are several modes under which the tool can run:
29+
30+
- `-hyde-json` - (default) Output an analysis dump of the input file as JSON
31+
- `-hyde-validate` - Validate existing YAML documentation
32+
- `-hyde-update` - Write updated YAML documentation
33+
34+
- `-hyde-src-root = <path>` - The root path to the header file(s) being analyzed. Affects `defined-in-file` output values by taking out the root path.
35+
- `-hyde-yaml-dir = <path>` - Root directory for YAML validation / update. Required for either hyde-validate or hyde-update modes.
36+
37+
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:
38+
39+
hyde input_file.hpp -hyde-json -- -x c++ -I/path/to/includes
40+
41+
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`.
42+
43+
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.
44+
45+
# Examples:
46+
47+
To output JSON:
48+
```./hyde ../test_files/apollo.hpp --```
49+
50+
To validate pre-existing YAML:
51+
```./hyde ../test_files/apollo.json -hyde-yaml-dir=/path/to/output -hyde-validate```
52+
53+
To output updated YAML:
54+
```./hyde ../test_files/apollo.json -hyde-yaml-dir=/path/to/output -hyde-update```

0 commit comments

Comments
 (0)