Add consolidated events documentation

Author: neongreen

lion/internal/extractor/extractor.go

@@ -23,13 +23,15 @@ type DocEntry struct {
 	HasSection    bool
 }
 
-//lion:implementation section="Extraction pipeline"
 // Extraction pipeline:
 //   - Walks all .go files under the directory, skipping *_test.go.
-//   - Parses with comments and pulls lion markers from package doc, func doc, and type/const/var
-//     doc comments (first name in a const/var block is used as the entity).
+//   - Parses with comments and pulls lion markers from package doc, func doc, type/const/var
+//     doc comments, and inline comments inside functions and other declarations (first name in a
+//     const/var block is used as the entity).
 //   - Supports single-line markers and block comment markers (marker at top of the doc block).
 //   - Aggregates snippets per topic across files; generator writes one file per topic.
+//
+//lion:implementation section="Extraction pipeline"
 func Extract(dir string) (map[string][]DocEntry, error) {
 	docs := make(map[string][]DocEntry)
 	fset := token.NewFileSet()
@@ -71,34 +73,55 @@ func Extract(dir string) (map[string][]DocEntry, error) {
 }
 
 func extractFromFile(fset *token.FileSet, file *ast.File, filepath string, docs map[string][]DocEntry) error {
+	processed := make(map[*ast.CommentGroup]bool)
+
 	// Extract package-level comments
 	if file.Doc != nil {
+		processed[file.Doc] = true
 		if err := extractFromCommentGroup(fset, file.Doc, filepath, "package "+file.Name.Name, docs); err != nil {
 			return err
 		}
 	}
 
-	var parseErr error
-	ast.Inspect(file, func(n ast.Node) bool {
-		if parseErr != nil {
-			return false
-		}
-		switch decl := n.(type) {
+	var funcDecls []*ast.FuncDecl
+	var genDecls []*ast.GenDecl
+
+	// Extract doc comments from declarations and record them as processed
+	for _, decl := range file.Decls {
+		switch d := decl.(type) {
 		case *ast.FuncDecl:
-			if decl.Doc != nil {
-				parseErr = extractFromCommentGroup(fset, decl.Doc, filepath, decl.Name.Name, docs)
+			funcDecls = append(funcDecls, d)
+			if d.Doc != nil {
+				processed[d.Doc] = true
+				if err := extractFromCommentGroup(fset, d.Doc, filepath, d.Name.Name, docs); err != nil {
+					return err
+				}
 			}
 		case *ast.GenDecl:
-			if decl.Doc != nil {
-				// For type/const/var declarations
-				entityName := getEntityName(decl)
-				parseErr = extractFromCommentGroup(fset, decl.Doc, filepath, entityName, docs)
+			genDecls = append(genDecls, d)
+			if d.Doc != nil {
+				processed[d.Doc] = true
+				entityName := getEntityName(d)
+				if err := extractFromCommentGroup(fset, d.Doc, filepath, entityName, docs); err != nil {
+					return err
+				}
 			}
 		}
-		return true
-	})
+	}
+
+	// Extract inline lion comment groups that were not attached as doc comments
+	for _, cg := range file.Comments {
+		if processed[cg] {
+			continue
+		}
+
+		entityName := determineEntityForComment(cg, file, funcDecls, genDecls)
+		if err := extractFromCommentGroup(fset, cg, filepath, entityName, docs); err != nil {
+			return err
+		}
+	}
 
-	return parseErr
+	return nil
 }
 
 // getEntityName extracts the entity name from a general declaration.
@@ -116,8 +139,24 @@ func getEntityName(decl *ast.GenDecl) string {
 	return ""
 }
 
-//lion:supported-syntax section="Supported syntax"
-//
+func determineEntityForComment(cg *ast.CommentGroup, file *ast.File, funcDecls []*ast.FuncDecl, genDecls []*ast.GenDecl) string {
+	for _, fn := range funcDecls {
+		if fn.Body != nil && cg.Pos() >= fn.Body.Pos() && cg.End() <= fn.Body.End() {
+			return fn.Name.Name
+		}
+	}
+
+	for _, gd := range genDecls {
+		if cg.Pos() >= gd.Pos() && cg.End() <= gd.End() {
+			if name := getEntityName(gd); name != "" {
+				return name
+			}
+		}
+	}
+
+	return "package " + file.Name.Name
+}
+
 // Supported syntax formats:
 //
 //  1. Single-line marker first:
@@ -137,6 +176,7 @@ func getEntityName(decl *ast.GenDecl) string {
 // All formats attach documentation to the next declaration (function, type, const, var).
 //
 //lion:supported-syntax section="Supported syntax"
+//lion:supported-syntax section="Supported syntax"
 func extractFromCommentGroup(fset *token.FileSet, cg *ast.CommentGroup, filepath, entityName string, docs map[string][]DocEntry) error {
 	topicGroups := make(map[string][]string)
 	topicOrder := []string{}
@@ -290,13 +330,13 @@ func parseLionCommentLine(text string) (string, string, metaInfo, error) {
 }
 
 /*
-	lion:errors-and-validation section="Error handling"
-	Validation and error handling:
-	- Invalid or empty topics are ignored silently (no explicit validation yet).
-	- Conflicting topic/section titles within the same comment group fail extraction with file:line.
-	- Comments that do not attach to package/func/type/const/var doc groups are skipped.
-	- CLI exits non-zero only when extraction fails (parse/metadata error) or generation fails (write error).
-	- Bad markers inside otherwise valid files do not stop extraction; they are just skipped.
+lion:errors-and-validation section="Error handling"
+Validation and error handling:
+- Invalid or empty topics are ignored silently (no explicit validation yet).
+- Conflicting topic/section titles within the same comment group fail extraction with file:line.
+- Comments that do not attach to package/func/type/const/var doc groups are skipped.
+- CLI exits non-zero only when extraction fails (parse/metadata error) or generation fails (write error).
+- Bad markers inside otherwise valid files do not stop extraction; they are just skipped.
 */
 func parseLionBlockComment(text string) (string, string, metaInfo, error) {
 	// Remove "lion:" prefix

lion/internal/extractor/extractor_test.go

@@ -158,6 +158,51 @@ func Function2() {}
 	}
 }
 
+func TestExtractInlineComments(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	// Create file with inline lion comments inside a function body
+	file := filepath.Join(tmpDir, "inline.go")
+	content := `package inline
+
+func Execute() {
+        //lion:inline-semantics section="execute"
+        //lion:inline-semantics Describes runtime behavior inside the function body.
+        helper()
+        //lion:inline-semantics Additional details that should join the same entry.
+}
+`
+
+	if err := os.WriteFile(file, []byte(content), 0644); err != nil {
+		t.Fatalf("failed to create inline file: %v", err)
+	}
+
+	docs, err := Extract(tmpDir)
+	if err != nil {
+		t.Fatalf("Extract failed: %v", err)
+	}
+
+	entries, ok := docs["inline-semantics"]
+	if !ok {
+		t.Fatalf("expected inline-semantics topic to be extracted")
+	}
+
+	if len(entries) != 3 {
+		t.Fatalf("expected 3 entries, got %d", len(entries))
+	}
+
+	for _, entry := range entries {
+		if entry.Entity != "Execute" {
+			t.Fatalf("expected entity Execute, got %s", entry.Entity)
+		}
+	}
+
+	combined := entries[0].Content + entries[1].Content + entries[2].Content
+	if !strings.Contains(combined, "runtime behavior") || !strings.Contains(combined, "Additional details") {
+		t.Fatalf("unexpected combined content: %q", combined)
+	}
+}
+
 func TestExtractSkipsTestFiles(t *testing.T) {
 	tmpDir := t.TempDir()
 
@@ -424,7 +469,7 @@ func TestExtractMarkerAtTopWithFollowingComments(t *testing.T) {
 
 	// Create test Go file with marker-at-top format that gathers following lines
 	testFile := filepath.Join(tmpDir, "test.go")
-content := `//lion:overview section="Overview section"
+	content := `//lion:overview section="Overview section"
 //
 // This is a multi-line comment.
 // It describes the functionality.

tk/docs/event.project.alias.add.md

@@ -0,0 +1,6 @@
+# Event.project.alias.add
+
+## project.alias.add
+
+*Source: `tk/internal/reducer/project.go:26`*
+

tk/docs/event.project.alias.remove.md

@@ -0,0 +1,6 @@
+# Event.project.alias.remove
+
+## project.alias.remove
+
+*Source: `tk/internal/reducer/project.go:32`*
+

tk/docs/event.project.created.md

@@ -0,0 +1,6 @@
+# Event.project.created
+
+## project.created
+
+*Source: `tk/internal/reducer/project.go:20`*
+

tk/docs/event.project.delete.md

@@ -0,0 +1,6 @@
+# Event.project.delete
+
+## project.delete
+
+*Source: `tk/internal/reducer/project.go:38`*
+

tk/docs/event.project.name.set.md

@@ -0,0 +1,6 @@
+# Event.project.name.set
+
+## project.name.set
+
+*Source: `tk/internal/reducer/project.go:44`*
+

tk/docs/event.relation.add.md

@@ -0,0 +1,6 @@
+# Event.relation.add
+
+## relation.add
+
+*Source: `tk/internal/reducer/reducer.go:49`*
+

tk/docs/event.relation.note.md

@@ -0,0 +1,6 @@
+# Event.relation.note
+
+## relation.note
+
+*Source: `tk/internal/reducer/reducer.go:61`*
+

tk/docs/event.relation.remove.md

@@ -0,0 +1,6 @@
+# Event.relation.remove
+
+## relation.remove
+
+*Source: `tk/internal/reducer/reducer.go:55`*
+