Refined README.md with comprehensive documentation improvements

README.md

@@ -1,63 +1,227 @@
 # rdeadcode
 
-Parse the output of [deadcode](https://go.dev/blog/deadcode) and remove(rewrite) the dead code from the source files.
+[![Go](https://github.com/yyoshiki41/rdeadcode/workflows/Go/badge.svg)](https://github.com/yyoshiki41/rdeadcode/actions)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/yyoshiki41/rdeadcode)](https://golang.org/)
+[![Go Report Card](https://goreportcard.com/badge/github.com/yyoshiki41/rdeadcode)](https://goreportcard.com/report/github.com/yyoshiki41/rdeadcode)
+
+A powerful Go tool that automatically removes dead code from your projects by parsing the output of Go's built-in [deadcode](https://go.dev/blog/deadcode) analyzer and rewriting source files to eliminate unused functions, methods, and variables.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Direct File/Function Removal](#direct-filefunction-removal)
+  - [Command Line Options](#command-line-options)
+- [Examples](#examples)
+- [Known Issues](#known-issues)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Automated Dead Code Removal**: Automatically removes dead functions, methods, and variables from Go source files
+- **Seamless Integration**: Works directly with Go's built-in `deadcode` tool output
+- **Multiple Input Methods**: Supports JSON file input, stdin, or direct file/function specification
+- **File Pattern Matching**: Ignore specific files using glob patterns
+- **Safe Operation**: Preserves code structure and formatting while removing only identified dead code
+- **Batch Processing**: Process multiple files and functions in a single operation
 
 ## Installation
 
+Install `rdeadcode` using Go's package manager:
+
 ```shell
 go install github.com/yyoshiki41/rdeadcode@latest
 ```
 
+**Requirements:**
+- Go 1.24.1 or later
+- The `deadcode` tool (available in Go 1.22+)
+
 ## Usage
 
+### Basic Usage
+
+The most common way to use `rdeadcode` is in combination with Go's `deadcode` tool:
+
 ```shell
+# Analyze and remove dead code from your project
 deadcode -json -test ./path/to/your/project | rdeadcode
 ```
 
-or
+Alternatively, you can save the deadcode output to a file and process it later:
 
 ```shell
+# Generate deadcode analysis
+deadcode -json -test ./my-project > deadcode.json
+
+# Process the analysis and remove dead code
 rdeadcode -json deadcode.json
 ```
 
-### Independent features of `rdeadcode`
+### Direct File/Function Removal
 
-Pass the argument `-file` and `-function` to remove the dead code from the file.
+For targeted dead code removal, you can specify individual files and functions:
 
 ```shell
+# Remove a specific dead function from a file
 rdeadcode -file path/to/your/file.go -function deadFunction
 ```
 
-#### -help
+### Command Line Options
+
 ```shell
 $ rdeadcode -help
 Usage of rdeadcode:
   -json string
-    	JSON file generated by deadcode
+        JSON file generated by deadcode (use "-" for stdin)
   -file string
-    	File to remove function from
+        File to remove function from
   -function string
-    	Function to remove
+        Function to remove
   -ignore string
-    	Ignore files matching glob pattern
+        Ignore files matching glob pattern
 ```
 
-## Known issues
+**Options:**
+- `-json`: Path to JSON file generated by `deadcode`, or "-" to read from stdin
+- `-file`: Specific Go source file to process  
+- `-function`: Name of the function to remove (requires `-file`)
+- `-ignore`: Glob pattern for files to ignore during processing
 
-> [!WARNING]
-> _deadcode_ detects methods that implement an interface as dead code if it is not used in the project.
+## Examples
 
-Please verify the interface compliance at compile time and restore the method when rdeadcode removes it.
+### Example 1: Full Project Analysis
+
+```shell
+# Run deadcode analysis and immediately process results
+cd my-go-project
+deadcode -json -test . | rdeadcode
+```
+
+### Example 2: Batch Processing with File Output
+
+```shell
+# Generate analysis report
+deadcode -json -test ./... > analysis.json
+
+# Review the analysis (optional)
+cat analysis.json | jq '.[].funcs[].name'
+
+# Remove identified dead code
+rdeadcode -json analysis.json
+```
+
+### Example 3: Ignoring Specific Files
+
+```shell
+# Ignore test files and vendor directory
+deadcode -json -test . | rdeadcode -ignore "**/*_test.go,vendor/**"
+```
+
+### Example 4: Targeted Function Removal
+
+```shell
+# Remove specific functions you know are dead
+rdeadcode -file internal/utils/helpers.go -function unusedHelper
+rdeadcode -file pkg/legacy/deprecated.go -function oldFunction
+```
+
+## Known Issues
+
+> [!WARNING]  
+> **Interface Implementation Detection**: The `deadcode` tool may incorrectly identify methods that implement an interface as dead code if those methods are not explicitly called within the analyzed codebase.
+
+When `rdeadcode` removes interface methods, it can break interface compliance. To prevent this:
+
+### Best Practice: Verify Interface Compliance
+
+Always verify interface compliance at compile time to protect critical interface methods:
 
 ```go
 // Verify interface compliance at compile time
-var _ fmt.Stringer = myString{}
+var _ fmt.Stringer = (*myString)(nil)
 
 type myString struct {
-	Value string
+    Value string
 }
 
 func (s myString) String() string {
-	return s.Value
+    return s.Value
 }
 ```
+
+### Mitigation Strategies
+
+1. **Use explicit interface compliance checks** (shown above)
+2. **Review deadcode output** before running `rdeadcode` in production
+3. **Test thoroughly** after running dead code removal
+4. **Use version control** to easily revert changes if needed
+5. **Consider using `-ignore` patterns** for files containing interface implementations
+
+### Recovering from Accidental Removal
+
+If `rdeadcode` accidentally removes interface methods:
+
+```shell
+# Revert changes using git
+git checkout HEAD~1 -- path/to/affected/file.go
+
+# Or restore from backup
+cp backup/file.go path/to/affected/file.go
+```
+
+## Contributing
+
+Contributions are welcome! Here's how you can help:
+
+### Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/yourusername/rdeadcode.git`
+3. Create a feature branch: `git checkout -b feature-name`
+4. Make your changes
+5. Run tests: `go test ./...`
+6. Commit your changes: `git commit -am 'Add feature'`
+7. Push to the branch: `git push origin feature-name`
+8. Submit a pull request
+
+### Development Setup
+
+```shell
+# Clone the repository
+git clone https://github.com/yyoshiki41/rdeadcode.git
+cd rdeadcode
+
+# Install dependencies
+go mod download
+
+# Run tests
+go test -v ./...
+
+# Build the project
+go build -v .
+```
+
+### Running Tests
+
+```shell
+# Run all tests
+go test ./...
+
+# Run tests with coverage
+go test -cover ./...
+
+# Run specific tests
+go test -run TestMainGolden
+```
+
+## License
+
+This project is distributed under the terms of the license found in the repository. Please refer to the project's license file for more information.
+
+---
+
+**Note**: Always backup your code before running automated dead code removal tools. While `rdeadcode` is designed to be safe, it's recommended to use version control and review changes before committing them to production.