docgen

README

Cadence Documentation Generator

A tool to generate human-readable documentation for Cadence programs. Supports generating documentation for following declarations:

• Composite types (Contracts, Structs, Resources, Enums)
• Interfaces (Contract interfaces, Struct interfaces, Resource Interfaces)
• Functions and Parameters
• Event declarations

The tool currently supports generating documentation in Markdown format.

How To Run

Navigate to cadence-tools/docgen/cmd directory and run:

go run main.go <path_to_cadence_file> <output_dir>

Documentation Comments Format

The documentation comments ("doc-strings" / "doc-comments": line comments starting with ///, or block comments starting with /**) available in Cadence programs are processed by the tool, to produce human-readable documentations.

Markdown Support

Standard Markdown format is supported in doc-comments, with a bit of Cadence flavour. This means, any Markdown syntax used within the comments would be honoured and rendered like a standard Markdown snippet. It gives the flexibility for the developers to write well-structured documentations.

e.g: A set of bullet points added using Markdown bullets syntax would be rendered as bullet points in the generated documentation as well.

Documentation Comment:

/// This is the description of the function. You can use markdown syntax here.
/// Can use **bold** or _italic_ texts, or even bullet-points:
///   - Here's the first point.
///   - Can also use code snippets (eg: `a + b`)

Output:

This is the description of the function. You can use markdown syntax here.
Can use bold or italic texts, or even bullet-points:

• Here's the first point.
• Can also use code snippets (eg: a + b)

Function Documentation

Function documentation may start with a description of the function. It also supports a special set of tags to document parameters and return types. Parameters can be documented using the @param tag, followed by the parameter name, a colon (:) and the parameter description. The return type can be documented using the @return tag.

/// This is the description of the function. This function adds two values.
///
/// @param a: First integer value to add
/// @param b: Second integer value to add
/// @return Addition of the two arguments `a` and `b`
///
pub fun add(a: Int, b: Int): Int {
}

Best Practices

• Avoid using headings, horizontal-lines in the documentation.
  • It could potentially conflict with the headers and lines added by the tool, when generating the documentation
  • This may cause the generated documentation to be rendered in a disorganized manner.
• Use inline-codes (within backticks `foo`) when referring to names/identifiers (such as function names, parameter names, etc.) in the code.

  /// This is the description of the function.
  /// This function adds `a` and `b` values.
  ///
  pub fun add(a: Int, b: Int): Int {
  }
  

• When documenting function parameters and return type, avoid mixing parameter/return-type documentations with the description of the function. e.g:

  /// This is the description of the function.
  ///
  /// @param a: First integer value to add
  /// @param b: Second integer value to add
  ///
  /// This function adds two values. However, this is not the proper way to document it.
  /// This part of the description is not in the proper place.
  ///
  /// @return Addition of the two arguments `a` and `b`
  ///
  pub fun add(a: Int, b: Int): Int {
  }
  

Documentation

Index

• type ASTDeclarationTemplateFunctions
  • func (ASTDeclarationTemplateFunctions) DeclKeywords(declaration ast.Declaration) string
  • func (ASTDeclarationTemplateFunctions) DeclTypeTitle(declaration ast.Declaration) string
  • func (ASTDeclarationTemplateFunctions) Enums(declarations []ast.Declaration) []ast.Declaration
  • func (ASTDeclarationTemplateFunctions) Events(declarations []ast.Declaration) []ast.Declaration
  • func (ASTDeclarationTemplateFunctions) GenInitializer(declaration ast.Declaration) bool
  • func (ASTDeclarationTemplateFunctions) HasConformance(declaration ast.Declaration) bool
  • func (ASTDeclarationTemplateFunctions) IsEnum(declaration ast.Declaration) bool
  • func (ASTDeclarationTemplateFunctions) StructsAndResources(declarations []ast.Declaration) []ast.Declaration
• type DocGenerator
  • func NewDocGenerator() *DocGenerator
  • func (gen *DocGenerator) Generate(source string, outputDir string) error
  • func (gen *DocGenerator) GenerateInMemory(source string) (InMemoryFiles, error)
• type ElementTemplateFunctions
• type InMemoryFileWriter
  • func NewInMemoryFileWriter(files InMemoryFiles, fileName string) *InMemoryFileWriter
  • func (w *InMemoryFileWriter) Close() error
  • func (w *InMemoryFileWriter) Write(bytes []byte) (n int, err error)
• type InMemoryFiles

Types

type ASTDeclarationTemplateFunctions

type ASTDeclarationTemplateFunctions struct{}

func (ASTDeclarationTemplateFunctions) DeclKeywords

func (ASTDeclarationTemplateFunctions) DeclKeywords(declaration ast.Declaration) string

func (ASTDeclarationTemplateFunctions) DeclTypeTitle

func (ASTDeclarationTemplateFunctions) DeclTypeTitle(declaration ast.Declaration) string

func (ASTDeclarationTemplateFunctions) Enums

func (ASTDeclarationTemplateFunctions) Enums(declarations []ast.Declaration) []ast.Declaration

func (ASTDeclarationTemplateFunctions) Events

func (ASTDeclarationTemplateFunctions) Events(declarations []ast.Declaration) []ast.Declaration

func (ASTDeclarationTemplateFunctions) GenInitializer

func (ASTDeclarationTemplateFunctions) GenInitializer(declaration ast.Declaration) bool

func (ASTDeclarationTemplateFunctions) HasConformance

func (ASTDeclarationTemplateFunctions) HasConformance(declaration ast.Declaration) bool

func (ASTDeclarationTemplateFunctions) IsEnum

func (ASTDeclarationTemplateFunctions) IsEnum(declaration ast.Declaration) bool

func (ASTDeclarationTemplateFunctions) StructsAndResources

func (ASTDeclarationTemplateFunctions) StructsAndResources(declarations []ast.Declaration) []ast.Declaration

type DocGenerator

type DocGenerator struct {
	// contains filtered or unexported fields
}

func NewDocGenerator

func NewDocGenerator() *DocGenerator

func (*DocGenerator) Generate

func (gen *DocGenerator) Generate(source string, outputDir string) error

func (*DocGenerator) GenerateInMemory

func (gen *DocGenerator) GenerateInMemory(source string) (InMemoryFiles, error)

type ElementTemplateFunctions

type ElementTemplateFunctions[T any] interface {
	HasConformance(T) bool
	IsEnum(T) bool
	DeclKeywords(T) string
	DeclTypeTitle(T) string
	GenInitializer(T) bool
	Enums(declarations []T) []T
	StructsAndResources([]T) []T
	Events([]T) []T
}

type InMemoryFileWriter

type InMemoryFileWriter struct {
	// contains filtered or unexported fields
}

func NewInMemoryFileWriter

func NewInMemoryFileWriter(files InMemoryFiles, fileName string) *InMemoryFileWriter

func (*InMemoryFileWriter) Close

func (w *InMemoryFileWriter) Close() error

func (*InMemoryFileWriter) Write

func (w *InMemoryFileWriter) Write(bytes []byte) (n int, err error)

type InMemoryFiles

type InMemoryFiles map[string][]byte