From ebe2c3658cf93fc88d12d6b284ae40875b6d3a93 Mon Sep 17 00:00:00 2001
From: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com>
Date: Tue, 9 Jan 2024 21:08:01 +0100
Subject: [PATCH] Add short top-level description of a crate

---
 crates/language/src/language.rs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/crates/language/src/language.rs b/crates/language/src/language.rs
index 49a87df35d..fdb086ebc6 100644
--- a/crates/language/src/language.rs
+++ b/crates/language/src/language.rs
@@ -1,7 +1,12 @@
-//! The `language` crate provides... ???
-
 #![warn(missing_docs)]
-
+//! The `language` crate provides a large chunk of Zed's language-related
+//! features (the other big contributors being project and lsp crates that revolve around LSP features).
+//! Namely, this crate:
+//! - Provides [`Language`], [`Grammar`] and [`LanguageRegistry`] types that
+//! use Tree-sitter to provide syntax highlighting to the editor; note though that `language` doesn't perform the highlighting by itself. It only maps ranges in a buffer to colors. Treesitter is also used for buffer outlines (lists of symbols in a buffer)
+//! - Exposes [`LanguageConfig`] that describes how constructs (like brackets or line comments) should be handled by the editor for a source file of a particular language.
+//!
+//! Notably we do *not* assign a single language to a single file; in real world a single file can consist of multiple programming languages - HTML is a good example of that - and `language` crate tends to reflect that status quo in it's API.
 mod buffer;
 mod diagnostic_set;
 mod highlight_map;