lion: Add marker-at-end format for cleaner multi-line documentation

Co-authored-by: neongreen <1523306+neongreen@users.noreply.github.com>

Author: Copilot

lion/README.md

@@ -55,9 +55,20 @@ The tool generates:
 
 ## Comment Format
 
-lion supports two comment formats:
+lion supports three comment formats:
 
-### Single-line format
+### 1. Marker at end (cleanest for multi-line)
+
+```go
+// Regular Go comment describing functionality.
+// Multiple lines without any lion prefix.
+// The marker at the end pulls in all preceding lines.
+//lion:topic-name
+```
+
+This is the **recommended format** for longer documentation blocks. It keeps your comments clean and readable - just regular Go comments with a single lion marker at the end.
+
+### 2. Single-line format
 
 ```
 //lion:topic-name Optional content describing this code element
@@ -67,7 +78,7 @@ lion supports two comment formats:
 - **Content**: Optional markdown-formatted text
 - Multiple consecutive `//lion:topic` lines are combined into one entry
 
-### Block comment format
+### 3. Block comment format
 
 ```go
 /*lion:topic-name
@@ -81,10 +92,27 @@ This makes documentation cleaner.
 - **Content**: All subsequent lines in the block comment
 - Cleaner for longer documentation blocks
 
-Both formats can be attached to functions, types, constants, variables, and package declarations.
+All formats can be attached to functions, types, constants, variables, and package declarations.
 
 ## Example
 
+Marker at end format (recommended):
+
+```go
+// lion is a documentation extraction tool.
+// Add lion comments to generate markdown docs.
+// This is the cleanest syntax for multi-line docs.
+//lion:getting-started
+package main
+
+// The main function initializes the app.
+// It handles setup and configuration.
+//lion:architecture
+func main() {
+    // ...
+}
+```
+
 Single-line format:
 
 ```go

lion/internal/extractor/extractor.go

@@ -101,12 +101,82 @@ func getEntityName(decl *ast.GenDecl) string {
 	return ""
 }
 
-//lion:implementation extractFromCommentGroup processes a comment group and extracts lion comments.
-//lion:implementation It groups consecutive lion comments by topic, combines their content, and creates DocEntry records.
-//lion:implementation This allows multiple lion comments on the same entity to be merged into a single documentation entry per topic.
-//lion:implementation Supports both single-line (//lion:topic) and block comment (/*lion:topic ... */) formats.
+/*lion:implementation
+extractFromCommentGroup processes a comment group and extracts lion comments.
+
+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.
+*/
 func extractFromCommentGroup(fset *token.FileSet, cg *ast.CommentGroup, filepath, entityName string, docs map[string][]DocEntry) {
-	// Group consecutive lion comments by topic
+	// First, check if the last comment is a lion marker (pulls entire comment group)
+	// This only applies if there are non-lion comments before it
+	if len(cg.List) > 1 {
+		lastComment := cg.List[len(cg.List)-1]
+		lastText := lastComment.Text
+		if strings.HasPrefix(lastText, "//") {
+			lastText = strings.TrimPrefix(lastText, "//")
+			lastText = strings.TrimSpace(lastText)
+			if strings.HasPrefix(lastText, "lion:") {
+				// Check if all preceding comments are NON-lion comments
+				hasOnlyRegularComments := true
+				for i := 0; i < len(cg.List)-1; i++ {
+					text := cg.List[i].Text
+					if strings.HasPrefix(text, "//") {
+						text = strings.TrimPrefix(text, "//")
+						text = strings.TrimSpace(text)
+						if strings.HasPrefix(text, "lion:") {
+							hasOnlyRegularComments = false
+							break
+						}
+					}
+				}
+				
+				// Only use marker-at-end if there are regular comments before the marker
+				if hasOnlyRegularComments {
+					// Extract topic from the last line
+					topic, markerContent := parseLionCommentLine(lastText)
+					if topic != "" {
+						// Collect all preceding comments as content
+						var contentLines []string
+						for i := 0; i < len(cg.List)-1; i++ {
+							text := cg.List[i].Text
+							if strings.HasPrefix(text, "//") {
+								text = strings.TrimPrefix(text, "//")
+								text = strings.TrimSpace(text)
+								if text != "" {
+									contentLines = append(contentLines, text)
+								}
+							}
+						}
+						
+						// Add marker content if provided
+						if markerContent != "" {
+							contentLines = append(contentLines, markerContent)
+						}
+						
+						if len(contentLines) > 0 {
+							pos := fset.Position(cg.List[0].Pos())
+							entry := DocEntry{
+								Topic:   topic,
+								Content: strings.Join(contentLines, "\n"),
+								File:    filepath,
+								Line:    pos.Line,
+								Entity:  entityName,
+							}
+							docs[topic] = append(docs[topic], entry)
+						}
+						return // Don't process individual comments
+					}
+				}
+			}
+		}
+	}
+	
+	// Otherwise, process comments individually (legacy behavior)
 	topicGroups := make(map[string][]string)
 	topicOrder := []string{}
 	var firstLine int

lion/internal/extractor/extractor_test.go

@@ -357,3 +357,149 @@ type Config struct {
 		t.Errorf("expected 1 api entry, got %d", len(apiEntries))
 	}
 }
+
+func TestExtractMarkerAtEnd(t *testing.T) {
+tmpDir := t.TempDir()
+
+// Create test Go file with marker-at-end format
+testFile := filepath.Join(tmpDir, "test.go")
+	content := `// This is a multi-line comment.
+// It describes the functionality.
+// The lion marker is at the end.
+//lion:overview
+package test
+
+
+// The Config struct holds settings.
+// Fields can be configured via files or environment.
+// This demonstrates the marker-at-end format.
+//lion:api
+type Config struct {
+Port int
+}
+
+// Initialize creates a new instance.
+// It sets up default values.
+//lion:api Additional info can go on the marker line
+func Initialize() *Config {
+return &Config{Port: 8080}
+}
+`
+
+if err := os.WriteFile(testFile, []byte(content), 0644); err != nil {
+t.Fatalf("failed to create test file: %v", err)
+}
+
+// Extract documentation
+docs, err := Extract(tmpDir)
+if err != nil {
+t.Fatalf("Extract failed: %v", err)
+}
+
+// Verify topics
+if len(docs) != 2 {
+t.Errorf("expected 2 topics, got %d", len(docs))
+}
+
+// Verify overview content
+overviewEntries := docs["overview"]
+if len(overviewEntries) != 1 {
+t.Errorf("expected 1 overview entry, got %d", len(overviewEntries))
+}
+if len(overviewEntries) > 0 {
+content := overviewEntries[0].Content
+if !strings.Contains(content, "multi-line comment") {
+t.Errorf("overview content missing expected text, got: %q", content)
+}
+if !strings.Contains(content, "lion marker is at the end") {
+t.Errorf("overview content missing expected text, got: %q", content)
+}
+// Should NOT contain the lion marker itself
+if strings.Contains(content, "lion:overview") {
+t.Errorf("overview content should not contain lion marker, got: %q", content)
+}
+}
+
+// Verify api content (should have 2 entries)
+apiEntries := docs["api"]
+if len(apiEntries) != 2 {
+t.Errorf("expected 2 api entries, got %d", len(apiEntries))
+}
+
+// First api entry (Config struct)
+if len(apiEntries) > 0 {
+content := apiEntries[0].Content
+if !strings.Contains(content, "Config struct holds settings") {
+t.Errorf("api content missing expected text, got: %q", content)
+}
+if !strings.Contains(content, "marker-at-end format") {
+t.Errorf("api content missing expected text, got: %q", content)
+}
+}
+
+// Second api entry (Initialize function) - should include marker line content
+if len(apiEntries) > 1 {
+content := apiEntries[1].Content
+if !strings.Contains(content, "Initialize creates a new instance") {
+t.Errorf("api content missing expected text, got: %q", content)
+}
+if !strings.Contains(content, "Additional info can go on the marker line") {
+t.Errorf("api content should include marker line content, got: %q", content)
+}
+}
+}
+
+func TestMixedCommentFormats(t *testing.T) {
+tmpDir := t.TempDir()
+
+// Test file that mixes all three formats
+testFile := filepath.Join(tmpDir, "test.go")
+	content := `// Format 1: Marker at end
+// This uses the cleanest syntax.
+//lion:format1
+package test
+
+//lion:format2 Format 2: Single-line with content on same line
+func format2example() {}
+
+/*lion:format3
+Format 3: Block comment
+with multiple lines
+*/
+func format3example() {}
+
+// Format 1 again: Another marker-at-end example
+// With multiple lines of documentation.
+//lion:format1
+func example() {}
+`
+
+if err := os.WriteFile(testFile, []byte(content), 0644); err != nil {
+t.Fatalf("failed to create test file: %v", err)
+}
+
+docs, err := Extract(tmpDir)
+if err != nil {
+t.Fatalf("Extract failed: %v", err)
+}
+
+// Should have 3 topics
+if len(docs) != 3 {
+t.Errorf("expected 3 topics, got %d", len(docs))
+}
+
+// Verify format1 has 2 entries
+if len(docs["format1"]) != 2 {
+t.Errorf("expected 2 format1 entries, got %d", len(docs["format1"]))
+}
+
+// Verify format2 has 1 entry
+if len(docs["format2"]) != 1 {
+t.Errorf("expected 1 format2 entry, got %d", len(docs["format2"]))
+}
+
+// Verify format3 has 1 entry
+if len(docs["format3"]) != 1 {
+t.Errorf("expected 1 format3 entry, got %d", len(docs["format3"]))
+}
+}