lion: Replace low-level docs with high-level user documentation examples

Copilot · neongreen · Copilot · commit c2f5126e8fa1 · 2025-11-23T11:49:04.000Z
Co-authored-by: neongreen &lt;1523306+neongreen@users.noreply.github.com&gt;
diff --git a/lion/doc.go b/lion/doc.go
@@ -0,0 +1,87 @@
+// Getting Started:
+//
+// 1. Install lion: go install github.com/neongreen/mono/lion@latest
+// 2. Add lion comments to your Go code
+// 3. Run: lion generate
+// 4. Check the ./docs directory for generated markdown
+//
+// That's it! Lion will create one markdown file per topic.
+//lion:getting-started
+package main
+
+// Best Practices:
+//
+// - Use marker-at-end format for cleaner code (recommended)
+// - Choose descriptive topic names (e.g., "getting-started", "api-reference")
+// - Group related documentation under the same topic
+// - Use hyphens in topic names, not spaces or underscores
+// - Keep topics focused - split large topics into smaller ones
+//
+// Topic names become filenames, so keep them filesystem-friendly.
+//lion:best-practices
+const _ = 0
+
+// Common Use Cases:
+//
+// 1. Project guides: Create "getting-started", "installation", "configuration" topics
+// 2. Architecture docs: Use "architecture", "design-decisions", "data-flow" topics
+// 3. API documentation: Create "api-overview", "endpoints", "authentication" topics
+// 4. Troubleshooting: Use "troubleshooting", "faq", "known-issues" topics
+//
+// Lion works best for narrative documentation that explains concepts,
+// not for API reference (use godoc for that).
+//lion:use-cases
+const __ = 0
+
+// Syntax Reference:
+//
+// Format 1 - Marker at end (recommended):
+//   // Regular comment lines
+//   // explaining functionality
+//   //lion:topic-name
+//
+// Format 2 - Single line:
+//   //lion:topic-name Your content here
+//
+// Format 3 - Block comment:
+//   /*lion:topic-name
+//   Your multi-line
+//   content here
+//   */
+//
+// All three formats generate identical output.
+// Choose the one that fits your documentation style.
+//lion:syntax-reference
+const ___ = 0
+
+// Known Limitations:
+//
+// - Only processes .go files (not .md, .txt, etc.)
+// - Skips *_test.go files automatically
+// - Package comments must be BEFORE the package keyword
+// - No support for nested topics or hierarchies
+// - No cross-referencing between topics (yet)
+// - Output is always markdown (no HTML, PDF, etc.)
+//
+// These are intentional design decisions to keep lion simple and focused.
+//lion:known-limitations
+const ____ = 0
+
+// Troubleshooting:
+//
+// Problem: "No documentation topics found"
+// Solution: Check that you're using the correct syntax and running
+//          lion in the right directory.
+//
+// Problem: Package-level docs not showing up
+// Solution: Make sure the lion comment comes BEFORE "package foo"
+//
+// Problem: Marker-at-end not working
+// Solution: Ensure all lines before //lion:topic are regular comments
+//          (no other //lion: markers in that comment block)
+//
+// Problem: Generated docs look wrong
+// Solution: Topics are combined from all files. Check for duplicate
+//          topics in different files that might be merging.
+//lion:troubleshooting
+const _____ = 0
diff --git a/lion/docs/architecture.md b/lion/docs/architecture.md
@@ -26,13 +26,13 @@ runGenerate implements the generate command workflow.
 
 It first extracts documentation using the extractor package, then generates markdown files using the generator package.
 
-*Source: `main.go:70`*
+*Source: `main.go:86`*
 
 ## runTopics
 
 runTopics implements the topics command.
 
 It extracts documentation and prints a list of unique topic names found in the source code.
 
-*Source: `main.go:93`*
+*Source: `main.go:109`*
 
diff --git a/lion/docs/best-practices.md b/lion/docs/best-practices.md
@@ -0,0 +1,14 @@
+# Best Practices
+
+## _
+
+Best Practices:
+- Use marker-at-end format for cleaner code (recommended)
+- Choose descriptive topic names (e.g., "getting-started", "api-reference")
+- Group related documentation under the same topic
+- Use hyphens in topic names, not spaces or underscores
+- Keep topics focused - split large topics into smaller ones
+Topic names become filenames, so keep them filesystem-friendly.
+
+*Source: `doc.go:12`*
+
diff --git a/lion/docs/cli.md b/lion/docs/cli.md
@@ -6,21 +6,5 @@ The root command defines the main entry point for the lion CLI.
 
 It uses Cobra for command-line parsing and includes subcommands for generate, topics, and version.
 
-*Source: `main.go:17`*
-
-## generateCmd
-
-The generate command scans Go files and creates markdown documentation.
-
-It accepts an optional directory argument and an --output flag to specify where markdown files should be written.
-
-*Source: `main.go:28`*
-
-## topicsCmd
-
-The topics command lists all documentation topics found in the codebase.
-
-This is useful for getting an overview of available documentation before generating files.
-
-*Source: `main.go:41`*
+*Source: `main.go:20`*
 
diff --git a/lion/docs/getting-started.md b/lion/docs/getting-started.md
@@ -0,0 +1,22 @@
+# Getting Started
+
+## package main
+
+Getting Started:
+1. Install lion: go install github.com/neongreen/mono/lion@latest
+2. Add lion comments to your Go code
+3. Run: lion generate
+4. Check the ./docs directory for generated markdown
+That's it! Lion will create one markdown file per topic.
+
+*Source: `doc.go:1`*
+
+## package main
+
+lion extracts documentation from special comments in Go source code.
+It's designed for creating higher-level documentation like guides and references.
+This package demonstrates using lion for user-facing documentation rather than
+API documentation (which is what godoc is for).
+
+*Source: `main.go:1`*
+
diff --git a/lion/docs/implementation.md b/lion/docs/implementation.md
@@ -19,10 +19,11 @@ It extracts lion comments from package declarations, function declarations, and
 ## extractFromCommentGroup
 
 extractFromCommentGroup processes a comment group and extracts lion comments.
-
-It groups consecutive lion comments by topic, combines their content, and creates DocEntry records.
-
-This allows multiple lion comments on the same entity to be merged into a single documentation entry per topic.
+It supports three formats:
+1. Single-line: //lion:topic Content (repeated on each line)
+2. Block: slash-star lion:topic Multi-line content star-slash
+3. Marker at end: Regular // comments followed by //lion:topic (pulls entire comment block)
+The marker-at-end format is cleanest for longer documentation blocks.
 
 *Source: `internal/extractor/extractor.go:104`*
 
@@ -32,7 +33,19 @@ parseLionCommentLine parses a single lion comment line.
 
 The format is "lion:topic-name Optional content". It returns the topic name and content separately.
 
-*Source: `internal/extractor/extractor.go:161`*
+*Source: `internal/extractor/extractor.go:254`*
+
+## parseLionBlockComment
+
+parseLionBlockComment parses a block comment that starts with lion:topic-name.
+The format allows multi-line content without repeating the topic on each line:
+/*lion:topic-name
+Multi-line content
+can go here
+*\/
+This returns the topic name and the full content (with the first line after lion:topic-name).
+
+*Source: `internal/extractor/extractor.go:275`*
 
 ## generateTopicFile
 
diff --git a/lion/docs/index.md b/lion/docs/index.md
@@ -5,6 +5,12 @@ This documentation was generated from lion comments in the source code.
 ## Topics
 
 - [Architecture](architecture.md)
+- [Best Practices](best-practices.md)
 - [Cli](cli.md)
+- [Getting Started](getting-started.md)
 - [Implementation](implementation.md)
-- [Overview](overview.md)
+- [Known Limitations](known-limitations.md)
+- [Syntax Reference](syntax-reference.md)
+- [Troubleshooting](troubleshooting.md)
+- [Usage Guide](usage-guide.md)
+- [Use Cases](use-cases.md)
diff --git a/lion/docs/known-limitations.md b/lion/docs/known-limitations.md
@@ -0,0 +1,15 @@
+# Known Limitations
+
+## ____
+
+Known Limitations:
+- Only processes .go files (not .md, .txt, etc.)
+- Skips *_test.go files automatically
+- Package comments must be BEFORE the package keyword
+- No support for nested topics or hierarchies
+- No cross-referencing between topics (yet)
+- Output is always markdown (no HTML, PDF, etc.)
+These are intentional design decisions to keep lion simple and focused.
+
+*Source: `doc.go:57`*
+
diff --git a/lion/docs/syntax-reference.md b/lion/docs/syntax-reference.md
@@ -0,0 +1,21 @@
+# Syntax Reference
+
+## ___
+
+Syntax Reference:
+Format 1 - Marker at end (recommended):
+// Regular comment lines
+// explaining functionality
+//lion:topic-name
+Format 2 - Single line:
+//lion:topic-name Your content here
+Format 3 - Block comment:
+/*lion:topic-name
+Your multi-line
+content here
+*/
+All three formats generate identical output.
+Choose the one that fits your documentation style.
+
+*Source: `doc.go:36`*
+
diff --git a/lion/docs/troubleshooting.md b/lion/docs/troubleshooting.md
@@ -0,0 +1,19 @@
+# Troubleshooting
+
+## _____
+
+Troubleshooting:
+Problem: "No documentation topics found"
+Solution: Check that you're using the correct syntax and running
+lion in the right directory.
+Problem: Package-level docs not showing up
+Solution: Make sure the lion comment comes BEFORE "package foo"
+Problem: Marker-at-end not working
+Solution: Ensure all lines before //lion:topic are regular comments
+(no other //lion: markers in that comment block)
+Problem: Generated docs look wrong
+Solution: Topics are combined from all files. Check for duplicate
+topics in different files that might be merging.
+
+*Source: `doc.go:70`*
+
diff --git a/lion/docs/usage-guide.md b/lion/docs/usage-guide.md
@@ -0,0 +1,23 @@
+# Usage Guide
+
+## generateCmd
+
+The generate command is the main way to use lion.
+Run it in a directory containing Go files with lion comments.
+Example:
+lion generate ./myproject --output ./docs
+This will scan all .go files in ./myproject and create markdown files
+in the ./docs directory, one file per topic.
+
+*Source: `main.go:31`*
+
+## topicsCmd
+
+The topics command helps you discover what documentation topics exist.
+Use it to see what will be generated before running 'lion generate'.
+Example:
+lion topics ./myproject
+This lists all unique topic names found in lion comments.
+
+*Source: `main.go:51`*
+
diff --git a/lion/docs/use-cases.md b/lion/docs/use-cases.md
@@ -0,0 +1,14 @@
+# Use Cases
+
+## __
+
+Common Use Cases:
+1. Project guides: Create "getting-started", "installation", "configuration" topics
+2. Architecture docs: Use "architecture", "design-decisions", "data-flow" topics
+3. API documentation: Create "api-overview", "endpoints", "authentication" topics
+4. Troubleshooting: Use "troubleshooting", "faq", "known-issues" topics
+Lion works best for narrative documentation that explains concepts,
+not for API reference (use godoc for that).
+
+*Source: `doc.go:24`*
+
diff --git a/lion/internal/extractor/extractor.go b/lion/internal/extractor/extractor.go
@@ -323,3 +323,13 @@ func parseLionBlockComment(text string) (string, string) {
 	content := strings.Join(contentLines, "\n")
 	return topic, content
 }
+
+// Lion has some known limitations:
+//
+// - Only works with Go source files (.go extension)
+// - Skips test files (*_test.go) automatically
+// - Package-level comments must come BEFORE the package keyword
+// - Marker-at-end only works when all preceding comments are non-lion comments
+//
+// These are by design to keep the tool simple and focused.
+//lion:known-issues
diff --git a/lion/main.go b/lion/main.go
@@ -1,6 +1,9 @@
-//lion:overview lion is a documentation extraction tool for Go code.
-//lion:overview It scans Go source files for special //lion:topic-name comments and generates organized markdown documentation.
-//lion:overview This allows you to build book-like documentation by adding comments throughout your codebase that contribute to different chapters.
+// lion extracts documentation from special comments in Go source code.
+// It's designed for creating higher-level documentation like guides and references.
+//
+// This package demonstrates using lion for user-facing documentation rather than
+// API documentation (which is what godoc is for).
+//lion:getting-started
 package main
 
 import (
@@ -25,8 +28,15 @@ Use //lion:topic-name comments in your Go code to mark documentation for specifi
 Run 'lion generate' to create markdown documentation files organized by topic.`,
 }
 
-//lion:cli The generate command scans Go files and creates markdown documentation.
-//lion:cli It accepts an optional directory argument and an --output flag to specify where markdown files should be written.
+// The generate command is the main way to use lion.
+// Run it in a directory containing Go files with lion comments.
+// 
+// Example:
+//   lion generate ./myproject --output ./docs
+//
+// This will scan all .go files in ./myproject and create markdown files
+// in the ./docs directory, one file per topic.
+//lion:usage-guide
 var generateCmd = &cobra.Command{
 	Use:   "generate [directory]",
 	Short: "Generate markdown documentation from Go code",
@@ -38,8 +48,14 @@ and generates markdown files for each documentation topic found.`,
 	RunE: runGenerate,
 }
 
-//lion:cli The topics command lists all documentation topics found in the codebase.
-//lion:cli This is useful for getting an overview of available documentation before generating files.
+// The topics command helps you discover what documentation topics exist.
+// Use it to see what will be generated before running 'lion generate'.
+//
+// Example:
+//   lion topics ./myproject
+//
+// This lists all unique topic names found in lion comments.
+//lion:usage-guide
 var topicsCmd = &cobra.Command{
 	Use:   "topics [directory]",
 	Short: "List all documentation topics found in Go code",
