Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
45 lines (26 loc) · 3.11 KB

CONTRIBUTING.md

File metadata and controls

45 lines (26 loc) · 3.11 KB

APIView token parsers

This page describes how to contribute to APIView language level parsers. Specifically how to create or update a language parser to produce a hierarchy of the API using tokens with context, instead of a flat token list.

Benefits of token schema with parent - child context

  • Ability to granularly identify a specific node and it's sub nodes. For e.g. if a review line for a class is available then all it's child nodes contain all methods and properties within that class.
  • Faster diffing using tree shaker instead of current text based comparison.
  • Provide diffing with context of where the line that changed belong to in the tree, instead of showing the 5 lines before and after the change.
  • Provide cross language view for a granular section within an API review.
  • Less data to be stored in token file which are located in azure storage blob.

Key concepts

APIView token schema is available in TypeSpec and JSON. Parser needs to create a CodeFile object as per the schema. CodeFile object contains a metadata about the package and array of ReviewLine object. Each object of review line in CodeFile object is a top level lines to be listed. For e.g. Top level lines are mostly namespace or module level nodes. Each ReviewLine object has children of ReviewLine to include sub nodes that needs to be listed in a review.

A sample token file is present here.

APIView generates navigation tree based on the information in token. A token is included in the navigation tree if NavigatonDisplayName is set in ReviewToken and LineId is set in ReviewLine object that contains the ReviewToken

Serialization

Serialize the generated code file to JSON. The output file should have .json extension. Try to make the json as small as possible by ignoring null values and empty collections. Don't worry about indentation that will be handled by the tree structure based on the parent - child relationship among ReviewLine objects.

Examples

A sample token file for .NET package Azure.Template is present here and corresponding rendered text representation is available here.

JSON token validation

You can validate JSON tokens against required JSON schema using JSON schema validator.

  • Select Custom as schema type and copy and paste the contents in json schema to left panel.
  • Generate API view token file and paste generated JSON content onto right side panel to validate.

Get help

Please reach out at APIView Teams Channel if you need more information.
⚡