This patch refactors CommentKind handling in clang-doc by introducing a
strongly typed enum class for better type safety and clarity. It updates
all relevant places, including YAML traits and serialization, to work
with the new enum. Additionally, it enhances the Mustache-based HTML
generation by fully supporting all comment kinds, ensuring accurate
structured rendering of comment blocks. The changes simplify future
maintenance, improve robustness by eliminating unchecked defaults, and
ensure consistency between generators.
Fixes https://github.com/llvm/llvm-project/issues/142083
This patch adds start and end line numbers to clang-doc. Currently
clang-doc only encodes the start line numbers of records, struct, etc.
This patch adds start and end line number to clang-doc bitcode which is
passed to the generator. This will be used by the mustache backend to
generate line ranges. Based on the orginal patch in #135081.
Co-author: Paul Kirth <paulkirth@google.com>
Co-authored-by: PeterChou1 <peter.chou@mail.utoronto.ca>
This PR adds a new command-line option that allows users to specify the
prefix used for line-based anchors in repository URLs. Different
repository interfaces use different formats for line anchors (GitHub
uses `#L123`, googlesource uses `#123`, etc.). This option enables users
to customize the line prefix to match their repository platform without
requiring hard-coded values for each service.
Fixes#59814
Currently, when we set URLs from JS, we set them only using the protocol
and host locations. This works fine when docs are served from the base
directory of the site, but if you want to nest it under another
directory, our JS fails to set the correct path, leading to broken
links.
This patch adds a --base option to specify the path prefix to use, which
is set in the generated index_json.js file. index.json can then fill in
the prefix appropriately when generating links in a browser. This flag
has no effect for non HTML output.
Given an index hosted at: www.docs.com/base_directory/index.html
we used to generate the following link:
www.docs.com/file.html
Using --base base_directory we now generate:
www.docs.com/base_directory/file.html
This allows such links to work when hosting pages without using a custom
index.js.
The current check in writeFileDefinition() is incorrect, and prevents us
from ever emitting the URL from the clang-doc tool. The unit tests do
test this, but call the API directly circumventing the check.
This is the first step towards addressing #59814.
Part of https://github.com/llvm/llvm-project/issues/101129
This patch adds support for attaching comments to enums for HTML in
clang-doc. It changes the enum generation to table tags where as
perviously we're using lists which is more in line with what other doc
generators are doing. It also gives clang-doc the ability to show user
specified enum values
Reapply https://github.com/llvm/llvm-project/pull/94717
Adds a new option --asset which allows users to specified the asset
folder for the html output of clang-doc.
This patch adds a better test for --asset option + fixes bug where
clang-doc assumes that user supplied js file is assume to be index.js
Reads template information from the AST and adds template parameters and
specialization information to the corresponding clang-doc structures.
Add a "QualName" to the Reference struct which includes the full
qualified type name. The Reference object represents a link in the
HTML/MD generators so is based on the unqualified name. But this does
not encode C-V qualifiers or template information that decorate the
name. The new QualName member encodes all of this information and also
makes it easier for the generators or downsteam YAML consumers to
generate the full name (before they had to process the "Path").
In test code that was changed, remove made-up paths to built-in types
like "int". In addition to slightnly cleaning up the code, these types
do not have paths in real execution, and generating incorrect references
to nonexistant data may complicate future changes in the generators.
Convert llvm::Optional to std::optional (YAML library requires this for
the new usage, and this makes everything consistent according to the
llvm::Optional -> std::optional transition).
Differential Revision: https://reviews.llvm.org/D139154
Reads template information from the AST and adds template parameters and
specialization information to the corresponding clang-doc structures.
Add a "QualName" to the Reference struct which includes the full
qualified type name. The Reference object represents a link in the
HTML/MD generators so is based on the unqualified name. But this does
not encode C-V qualifiers or template information that decorate the
name. The new QualName member encodes all of this information and also
makes it easier for the generators or downsteam YAML consumers to
generate the full name (before they had to process the "Path").
In test code that was changed, remove made-up paths to built-in types
like "int". In addition to slightnly cleaning up the code, these types
do not have paths in real execution, and generating incorrect references
to nonexistant data may complicate future changes in the generators.
Differential Revision: https://reviews.llvm.org/D139154
Read typedef and "using" type alias declarations and serialize into the
internal structures. Emit this information in the YAML output. The HTML
and MD generators are unchanged.
Separate out the logic to create the parent namespace or record object
and insert the newly created child into it. This logic was previously
duplicated for every "info" type and is now shared.
To help this, a struct containing the child vectors was separated out so
children can be added generically and without having too many templates.
A small change was made to populateParentNamespaces() to allow using
types that aren't themselves DeclContexts (typedefs are the first
example of this).
Differential Revision: https://reviews.llvm.org/D134371
Read typedef and "using" type alias declarations and serialize into the internal structures. Emit this information in the YAML output. The HTML and MD generators are unchanged.
Separate out the logic to create the parent namespace or record object and insert the newly created child into it. This logic was previously duplicated for every "info" type and is now shared.
To help this, a struct containing the child vectors was separated out so children can be added generically and without having too many templates.
A small change was made to populateParentNamespaces() to allow using types that aren't themselves DeclContexts (typedefs are the first example of this).
Reviewed By: paulkirth, haowei
Differential Revision: https://reviews.llvm.org/D134371
The *Info object (for the copy of the AST") constructors had many duplicated variants. Many of the variants seemed to be in an attempt to avoid default arguments. But default arguments are not prohibited and using them allows most of the variants to be removed which improves readability.
Remove the IsInGlobalNamespace flag on a Reference. This is set when the path is empty, and only read once in the HTML generator with the identical condition. The constructor cleanup exposed a problem where this was set to false when the constructor with no path was used, but true when the path was set to empty.
There should be no observable change with the exception that IsInGlobalNamespace is no longer emitted in YAML.
Reviewed By: paulkirth, haowei
Differential Revision: https://reviews.llvm.org/D134235
This change has two components. The moves the generated file
for a namespace to the directory named after the namespace in
a file named 'index.<format>'. This greatly improves the browsing
experience since the index page is shown by default for a directory.
The second improves the markdown output by adding the links to the
referenced pages for children objects and the link back to the source
code.
Patch By: Clayton
Differential Revision: https://reviews.llvm.org/D72954
This change has two components. The moves the generated file
for a namespace to the directory named after the namespace in
a file named 'index.<format>'. This greatly improves the browsing
experience since the index page is shown by default for a directory.
The second improves the markdown output by adding the links to the
referenced pages for children objects and the link back to the source
code.
Patch By: Clayton
Differential Revision: https://reviews.llvm.org/D72954
This change has two components. The moves the generated file
for a namespace to the directory named after the namespace in
a file named 'index.<format>'. This greatly improves the browsing
experience since the index page is shown by default for a directory.
The second improves the markdown output by adding the links to the
referenced pages for children objects and the link back to the source
code.
Patch By: Clayton
Differential Revision: https://reviews.llvm.org/D72954
The new design includes a header (contains the project name), a main section, and a footer.
The main section is divided into three subsections. Left, middle, right. The left section contains the general index, the middle contains the info's data, and the right contains the index for the info's content.
The CSS has been updated.
A flag --project-name is added.
The Attributes attribute of the TagNode struct is now a vector of pairs because these attributes should be rendered in the insertion order.
The functions (cpp and js) that converts an Index tree structure into HTML were slightly modified; the first ul tag created is now a ol tag. The inner lists are still ul.
Differential Revision: https://reviews.llvm.org/D66353
llvm-svn: 369139
Bitcode writer was not emitting the corresponding record for the Access attribute of a FunctionInfo. This has been added.
AS_none was being used as the default value for any AcesssSpecifier attribute
(in FunctionInfo and MemberTypeInfo), this has been changed to AS_public
because this is the enum value that evaluates to 0.
The bitcode writer doesn't write values that are 0 so if an attribute
was set to AS_public, this value is not written and after reading the
bitcode it would have the default value which is AS_none. This is why
the default value is now AS_public.
Differential Revision: https://reviews.llvm.org/D66151
llvm-svn: 369063
Now that we've moved to C++14, we no longer need the llvm::make_unique
implementation from STLExtras.h. This patch is a mechanical replacement
of (hopefully) all the llvm::make_unique instances across the monorepo.
Differential revision: https://reviews.llvm.org/D66259
llvm-svn: 368944
Path is now stored in the references to the child while serializing,
then this path is used to generate the relative path in the HTML
generator.
Now some references have paths and some don't so in the reducing phase,
references are now properly merged checking for empty attributes.
Tests added for HTML and YAML generators, merging and serializing.
computeRelativePath function had a bug when the filepath is part of the
given directory; it returned a path that starts with a separator. This
has been fixed.
Differential Revision: https://reviews.llvm.org/D65987
llvm-svn: 368602
Two command line options have been added to clang-doc.
--repository=<string> - URL of repository that hosts code; used for links to definition locations.
--source-root=<string> - Directory where processed files are stored. Links to definition locations will only be generated if the file is in this dir.
If the file is in the source-root and a repository options is passed;
a link to the source code will be rendered by the HTML generator.
Differential Revision: https://reviews.llvm.org/D65483
llvm-svn: 368460
This new index contains links to the main section of infos: Namespaces, Records, Functions, Enums, Members.
Also to each child function or enum.
Index is currently rendered on top of the info content, this will be fixed later with CSS.
Depends on D65690.
Differential Revision: https://reviews.llvm.org/D65030
llvm-svn: 368209
An index structure is created while generating the output file for each
info. This structure is parsed to JSON and written to a file in the
output directory. The html for the index is not rendered by clang-doc. A
Javascript file is included in the output directory, this will the JSON
file and insert HTML elements into the file.
Differential Revision: https://reviews.llvm.org/D65690
llvm-svn: 368070
Removes conversion of html paths in output. These will always be in
posix-style paths.
Differential Revision: https://reviews.llvm.org/D65425
llvm-svn: 367279
CSS files included in HTML should have a path in posix style, it should
not be different for Windows.
Differential Revision: https://reviews.llvm.org/D65309
llvm-svn: 367137
Tests on Windows were failing due to path separator differences.
'/' was being used as separator in the expected output, paths in expected output are now changed to their native form before comparing them to the actual output.
Differential Revision: https://reviews.llvm.org/D65306
llvm-svn: 367074
An option has been added to clang-doc to provide a list of css stylesheets that the user wants to use for the generated html docs.
Depends on D64539.
Differential Revision: https://reviews.llvm.org/D64938
llvm-svn: 367072
The children of a TagNode are rendered in the same line as the parent only if they are all TextNodes.
When children are not inline; two text nodes that are adjacent won't have a new line between them, each tag node is rendered in its own line.
Differential Revision: https://reviews.llvm.org/D65005
llvm-svn: 367050
Replace &, <, >, ", and ' with their corresponding html entities in text rendered
by HTML generator.
Differential Revision: https://reviews.llvm.org/D65107
llvm-svn: 367045
Tests on Windows were failing due to path separator differences.
'/' was being used as separator in the expected output, paths in expected
output are now changed to their native form before comparing them to the
actual output.
Committed on behalf of Diego Astiazarán (diegoaat97@gmail.com).
Differential Revision: https://reviews.llvm.org/D64669
llvm-svn: 365967
<a> tags are added for the parents and members of records and return type and
params of functions. The link redirects to the reference's info file.
The directory path where each info file will be saved is now generated in the
serialization phase and stored as an attribute in each Info.
Bitcode writer and reader were modified to handle the new attributes.
Committed on behalf of Diego Astiazarán (diegoaat97@gmail.com).
Differential Revision: https://reviews.llvm.org/D63663
llvm-svn: 365937
Implements an HTML generator.
Nodes are used to represent each part of the HTML file. There are TagNodes that
represent every HTML tag (p, h1, div, ...) and they have children nodes, which
can be TagNodes or TextNodes (these nodes only have text).
Proper indentation is rendered within the files generated by tool.
No styling (CSS) is included.
Committed on behalf of Diego Astiazarán (diegoaat97@gmail.com)
Differential Revision: https://reviews.llvm.org/D63857
llvm-svn: 365687
