diff --git a/doc/formatter.md b/doc/formatter.md index 574ed9d79..58a9d3eb9 100644 --- a/doc/formatter.md +++ b/doc/formatter.md @@ -25,7 +25,7 @@ The main functions that determine inter-token attributes are written as _priority-ordered rules_, i.e. series of `if (condition) return ...;`. There may be an _O(N^2)_ number of inter-token pair combinations, however, we aim to cover as much of that space as possible with few rules. -[Test cases](https://cs.opensource.google/verible/verible/+/master:verilog/formatting/token_annotator_test.cc), +[Test cases](https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/token-annotator_test.cc), however, should cover as much as possible explicitly, to prevent accidental regression. @@ -70,15 +70,15 @@ of work that is currently handled by the line-wrapping optimization phase. ### Tree unwrapping The implemention of [TreeUnwrapper] is split into -[language-agnostic library functions](https://cs.opensource.google/verible/verible/+/master:common/formatting/tree_unwrapper.cc) -and [Verilog-specific](https://cs.opensource.google/verible/verible/+/master:verilog/formatting/formatter.cc) code. +[language-agnostic library functions](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/tree-unwrapper.cc) +and [Verilog-specific](https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/formatter.cc) code. Simplified class inheritance diagram is shown below: ![Inheritance diagram](./formatter_simplified_class_diagram.png) [TreeUnwrapper] class exploits -the [Visitor](https://cs.opensource.google/verible/verible/+/master:common/text/visitors.h?q=class:SymbolVisitor&ss=verible%2Fverible) +the [Visitor](https://cs.opensource.google/verible/verible/+/master:verible/common/text/visitors.h?q=class:SymbolVisitor&ss=verible%2Fverible) pattern to recursively process the input CST tree: ```cpp // SymbolVisitor is an abstract visitor class from which visitors can be derived @@ -98,16 +98,16 @@ class SymbolVisitor { ``` It builds the [TokenPartitionTree] (i.e. `VectorTree`) with a set of helper methods to simplify the process: -* [`TraverseChildren()`](https://cs.opensource.google/verible/verible/+/master:common/formatting/tree_unwrapper.cc?q=function:TraverseChildren&ss=verible%2Fverible) - only traverses the CST -* [`VisitIndentedSection()`](https://cs.opensource.google/verible/verible/+/master:common/formatting/tree_unwrapper.cc?q=function:VisitIndentedSection&ss=verible%2Fverible) - creates indented section and traverses the CST -* [`VisitNewUnwrappedLine()`](https://cs.opensource.google/verible/verible/+/master:verilog/formatting/tree_unwrapper.cc?q=function:VisitNewUnwrappedLine&ss=verible%2Fverible) - begins a new partition of tokens and traverses the CST +* [`TraverseChildren()`](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/tree-unwrapper.cc?q=function:TraverseChildren&ss=verible%2Fverible) - only traverses the CST +* [`VisitIndentedSection()`](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/tree-unwrapper.cc?q=function:VisitIndentedSection&ss=verible%2Fverible) - creates indented section and traverses the CST +* [`VisitNewUnwrappedLine()`](https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/tree-unwrapper.cc?q=function:VisitNewUnwrappedLine&ss=verible%2Fverible) - begins a new partition of tokens and traverses the CST ### Custom policies application The next stage of code formatting is to apply custom functions that would reshape the partition tree according to the selected policy. An example of that are the [kTabularAlignment](#alignment) and the -[kAppendFittingSubPartitions](https://cs.opensource.google/verible/verible/+/master:common/formatting/unwrapped_line.h?q=kAppendFittingSubpartitions&ss=verible) +[kAppendFittingSubPartitions](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/unwrapped-line.h?q=kAppendFittingSubpartitions&ss=verible) policies. ### Wrapping @@ -157,14 +157,14 @@ syntax-structure similarity, insert spacing needed to achieve vertical alignment among the same substructure elements._ The implementation of tabular alignment for code is split into -[language-agnostic library functions](https://cs.opensource.google/verible/verible/+/master:common/formatting/align.h) +[language-agnostic library functions](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/align.h) and -[Verilog-specific](https://cs.opensource.google/verible/verible/+/master:verilog/formatting/align.cc) +[Verilog-specific](https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/align.cc) uses of alignment functions. To trigger alignment for a block of code, the [TreeUnwrapper] marks a [TokenPartitionTree] node with -[`kTabularAlignment`](https://cs.opensource.google/verible/verible/+/master:common/formatting/unwrapped_line.h?q=file:unwrapped_line.h%20usage:kTabularAlignment&ss=verible%2Fverible): +[`kTabularAlignment`](https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/unwrapped-line.h?q=file:unwrapped-line.h%20usage:kTabularAlignment&ss=verible%2Fverible): this says that a particular node has some children partitions that _could_ be aligned. @@ -173,7 +173,7 @@ done in the following phases: 1. **Language-specific:** Depending on the syntax tree node type that corresponds to each partition, a - [function](https://cs.opensource.google/verible/verible/+/master:verilog/formatting/align.cc?q=file:align.cc%20usage:kAlignHandlers&ss=verible%2Fverible) + [function](https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/align.cc?q=file:align.cc%20usage:kAlignHandlers&ss=verible%2Fverible) is chosen that is responsible for finding [AlignablePartitionGroup]s, blocks of children partitions that are candidates for aligned formatting. Think of these as groups of _rows_ that constitute a table. @@ -219,9 +219,9 @@ non-aligned formatting. -[UnwrappedLine]: https://cs.opensource.google/verible/verible/+/master:common/formatting/unwrapped_line.h -[token annotator]: https://cs.opensource.google/verible/verible/+/master:verilog/formatting/token_annotator.h -[InterTokenInfo]: https://cs.opensource.google/verible/verible/+/master:common/formatting/format_token.h;l=59?q=InterTokenInfo -[TreeUnwrapper]: https://cs.opensource.google/verible/verible/+/master:verilog/formatting/tree_unwrapper.h -[TokenPartitionTree]: https://cs.opensource.google/verible/verible/+/master:common/formatting/token_partition_tree.h -[AlignablePartitionGroup]: https://cs.opensource.google/verible/verible/+/master:common/formatting/align.h?q=file:align.h%20class:AlignablePartitionGroup&ss=verible%2Fverible +[UnwrappedLine]: https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/unwrapped-line.h +[token annotator]: https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/token-annotator.h +[InterTokenInfo]: https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/format-token.h;l=59?q=InterTokenInfo +[TreeUnwrapper]: https://cs.opensource.google/verible/verible/+/master:verible/verilog/formatting/tree-unwrapper.h +[TokenPartitionTree]: https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/token-partition-tree.h +[AlignablePartitionGroup]: https://cs.opensource.google/verible/verible/+/master:verible/common/formatting/align.h?q=file:align.h%20class:AlignablePartitionGroup&ss=verible%2Fverible diff --git a/doc/style_lint.md b/doc/style_lint.md index 6221e118a..b187e4d63 100644 --- a/doc/style_lint.md +++ b/doc/style_lint.md @@ -44,18 +44,18 @@ The major classes of text analyses available today are: * [LineLintRule] analyzes text one line at a time. Examples: - * [no_trailing_spaces_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/no_trailing_spaces_rule.h) - * [no_tabs_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/no_tabs_rule.h) + * [no_trailing_spaces_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/no-trailing-spaces-rule.h) + * [no_tabs_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/no-tabs-rule.h) * [TokenStreamLintRule] scans one token at a time. Examples: - * [endif_comment_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/endif_comment_rule.h) + * [endif_comment_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/endif-comment-rule.h) and - * [macro_name_style_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/macro_name_style_rule.h) + * [macro_name_style_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/macro-name-style-rule.h) * [SyntaxTreeLintRule] analyzes the syntax trees, examining tree nodes and leaves. The - [vast majority of SystemVerilog lint rules](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers) + [vast majority of SystemVerilog lint rules](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers) fall under this category. The [Analysis Tools](#syntax-tree-analysis-tools) section describes various syntax tree analysis tools. @@ -69,10 +69,10 @@ The major classes of text analyses available today are: aforementioned forms. Examples: - [module_filename_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/module_filename_rule.h?q=class:%5CbModuleFilenameRule), - [line_length_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/line_length_rule.h?q=class:%5CbLineLengthRule), + [module_filename_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/module-filename-rule.h?q=class:%5CbModuleFilenameRule), + [line_length_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/line-length-rule.h?q=class:%5CbLineLengthRule), and - [posix_eof_rule](https://cs.opensource.google/verible/verible/+/master:verilog/analysis/checkers/posix_eof_rule.h?q=class:%5CbPosixEOFRule). + [posix_eof_rule](https://cs.opensource.google/verible/verible/+/master:verible/verilog/analysis/checkers/posix-eof-rule.h?q=class:%5CbPosixEOFRule). For complete links to examples of each of the above lint rule classes, click on the class definition and navigate to "Extended By" inside the "Cross References" @@ -113,7 +113,7 @@ Cons: ### Syntax Tree Searching -[SearchSyntaxTree](https://cs.opensource.google/verible/verible/+/master:common/analysis/syntax_tree_search.h) +[SearchSyntaxTree](https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/syntax-tree-search.h) is a generic search function for identifying all syntax tree nodes that satisfy a given predicate. Searching with this function yields TreeSearchMatch objects that point to syntax tree nodes/leaves and include the context in which the node @@ -133,7 +133,7 @@ Cons: ### Syntax Tree Pattern Matching The -[CST Matcher library](https://cs.opensource.google/verible/verible/+/master:common/analysis/matcher/) +[CST Matcher library](https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/matcher/) provides a convenient way to create matcher objects that describe certain syntactic patterns. @@ -244,17 +244,17 @@ Make sure to include negative tests that expect no lint violations. [SV-LRM]: https://ieeexplore.ieee.org/document/8299595 -[LineLintRule]: https://cs.opensource.google/verible/verible/+/master:common/analysis/line_lint_rule.h -[TokenStreamLintRule]: https://cs.opensource.google/verible/verible/+/master:common/analysis/token_stream_lint_rule.h -[SyntaxTreeLintRule]: https://cs.opensource.google/verible/verible/+/master:common/analysis/syntax_tree_lint_rule.h -[TextStructureLintRule]: https://cs.opensource.google/verible/verible/+/master:common/analysis/text_structure_lint_rule.h -[TextStructureView]: https://cs.opensource.google/verible/verible/+/master:common/text/text_structure.h -[TreeContextVisitor]: https://cs.opensource.google/verible/verible/+/master:common/text/tree_context_visitor.h -[LintViolation]: https://cs.opensource.google/verible/verible/+/master:common/analysis/lint_rule_status.h?q=class:%5CbLintViolation%5Cb&ss=verible%2Fverible -[LintRuleStatus]: https://cs.opensource.google/verible/verible/+/master:common/analysis/lint_rule_status.h?q=class:%5CbLintRuleStatus%5Cb&ss=verible%2Fverible -[LintTestCase]: https://cs.opensource.google/verible/verible/+/master:common/analysis/linter_test_utils.h?q=class:%5CbLintTestCase%5Cb&ss=verible%2Fverible -[core_matchers.h]: https://cs.opensource.google/verible/verible/+/master:common/analysis/matcher/core_matchers.h -[verilog_matchers.h]: https://cs.opensource.google/verible/verible/+/master:verilog/CST/verilog_matchers.h -[TagMatchBuilder]: https://cs.opensource.google/verible/verible/+/master:common/analysis/matcher/matcher_builders.h?q=class:%5CbTagMatchBuilder%5Cb%20&ss=verible%2Fverible -[BindableMatcher]: https://cs.opensource.google/verible/verible/+/master:common/analysis/matcher/matcher.h?q=class:%5CbBindableMatcher%5Cb%20&ss=verible%2Fverible -[BoundSymbolManager]: https://cs.opensource.google/verible/verible/+/master:common/analysis/matcher/bound_symbol_manager.h?q=class:BoundSymbolManager&ss=verible%2Fverible +[LineLintRule]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/line-lint-rule.h +[TokenStreamLintRule]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/token-stream-lint-rule.h +[SyntaxTreeLintRule]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/syntax-tree-lint-rule.h +[TextStructureLintRule]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/text-structure-lint-rule.h +[TextStructureView]: https://cs.opensource.google/verible/verible/+/master:verible/common/text/text-structure.h +[TreeContextVisitor]: https://cs.opensource.google/verible/verible/+/master:verible/common/text/tree-context-visitor.h +[LintViolation]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/lint-rule-status.h?q=class:%5CbLintViolation%5Cb&ss=verible%2Fverible +[LintRuleStatus]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/lint-rule-status.h?q=class:%5CbLintRuleStatus%5Cb&ss=verible%2Fverible +[LintTestCase]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/linter-test-utils.h?q=class:%5CbLintTestCase%5Cb&ss=verible%2Fverible +[core_matchers.h]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/matcher/core-matchers.h +[verilog_matchers.h]: https://cs.opensource.google/verible/verible/+/master:verible/verilog/CST/verilog-matchers.h +[TagMatchBuilder]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/matcher/matcher-builders.h?q=class:%5CbTagMatchBuilder%5Cb%20&ss=verible%2Fverible +[BindableMatcher]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/matcher/matcher.h?q=class:%5CbBindableMatcher%5Cb%20&ss=verible%2Fverible +[BoundSymbolManager]: https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/matcher/bound-symbol-manager.h?q=class:BoundSymbolManager&ss=verible%2Fverible diff --git a/verible/verilog/CST/README.md b/verible/verilog/CST/README.md index 3ed5baf43..020ba322c 100644 --- a/verible/verilog/CST/README.md +++ b/verible/verilog/CST/README.md @@ -67,7 +67,7 @@ would pave the way to making an AST more useful. Most CST accessor function tests should follow this outline: * Declare an array of test data in the form of - [SyntaxTreeSearchTestCase](https://cs.opensource.google/verible/verible/+/master:common/analysis/syntax_tree_search_test_utils.h) + [SyntaxTreeSearchTestCase](https://cs.opensource.google/verible/verible/+/master:verible/common/analysis/syntax-tree-search-test-utils.h) * Each element compactly represents the code to analyze, and the set of expected findings as annotated subranges of text. * For every function-under-test, establish a function that extracts the @@ -75,5 +75,5 @@ Most CST accessor function tests should follow this outline: simple find-function on a syntax tree or contain any sequence of search refinements. * Pass these into the - [TestVerilogSyntaxRangeMatches](https://cs.opensource.google/verible/verible/+/master:verilog/CST/match_test_utils.h) + [TestVerilogSyntaxRangeMatches](https://cs.opensource.google/verible/verible/+/master:verible/verilog/CST/match-test-utils.h) test driver function which compare actual vs. expected subranges.