From b828358ccb399f1f56d31c59e2ef62f41281b89a Mon Sep 17 00:00:00 2001 From: Zach Allaun Date: Mon, 6 Nov 2023 09:36:02 -0500 Subject: [PATCH] Add note about analysis to `Ast` moduledoc --- apps/common/lib/lexical/ast.ex | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/apps/common/lib/lexical/ast.ex b/apps/common/lib/lexical/ast.ex index 82377b069..7db01af71 100644 --- a/apps/common/lib/lexical/ast.ex +++ b/apps/common/lib/lexical/ast.ex @@ -1,6 +1,19 @@ defmodule Lexical.Ast do @moduledoc """ - Utilities for working with syntax trees. + Utilities for analyzing Lexical documents as syntax trees. + + ## Analysis + + The preferred way to use this module is by first passing a document to + `analyze/1`, which returns a `%Lexical.Ast.Analysis{}` struct that + will have already parsed and analyzed a significant portion of the + document, thus reducing the cost of successive operations. + + An analysis looks at the entire AST, and thus may fail if the document + contains syntax errors that prevent parsing. To a partial analysis up + to a certain point (usually the cursor position), use `analyze_to/2`, + which analyzes the document up to the given position and can therefore + be used even if later parts of the document contain syntax errors. ## Differences from `Code`