Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation links to match moved filenames. #2294

Merged
merged 1 commit into from
Nov 23, 2024
Merged

Update documentation links to match moved filenames. #2294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions doc/formatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)
<!-- class diagram can be regenerated with yEd tool https://www.yworks.com/products/yed -->

[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
Expand All @@ -98,16 +98,16 @@ class SymbolVisitor {
```

It builds the [TokenPartitionTree] (i.e. `VectorTree<UnwrappedLine>`) 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
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -219,9 +219,9 @@ non-aligned formatting.
<!-- TODO: align vs. flush left behavior inferral -->
<!-- reference links -->

[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
48 changes: 24 additions & 24 deletions doc/style_lint.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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"
Expand Down Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -244,17 +244,17 @@ Make sure to include negative tests that expect no lint violations.
<!-- reference links -->

[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
4 changes: 2 additions & 2 deletions verible/verilog/CST/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,13 +67,13 @@ 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
targeted subranges of text (which must be non-overlapping). This could be a
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.
Loading