[FEATURE] - Improve code documentation;

Description

Some public methods and classes have minimal or missing documentation. Advanced features lack usage examples, and tracker-specific behaviors are not well documented.

Location

Files: All public API files, especially:

• lib/src/tracker/tracker.dart
• lib/src/tracker/http_tracker.dart
• lib/src/tracker/udp_tracker.dart
• lib/src/torrent_announce_tracker.dart
• lib/src/tracker/scrape.dart

Current Issues

1. Missing method documentation:

   • Some public methods lack dartdoc comments
   • Parameters not documented
   • Return values not explained
   • Exceptions not listed

2. Missing examples:

   • No examples for advanced features
   • No examples for optional parameters
   • Limited usage scenarios

3. Incomplete behavior documentation:

   • Tracker-specific behaviors not explained
   • Event handling not fully documented
   • Error scenarios not described

Expected Behavior

All public APIs should have:

1. Comprehensive dartdoc comments:

   • Clear description of purpose
   • All parameters documented
   • Return values explained
   • Exceptions listed
   • Usage examples

2. Class-level documentation:

   • Purpose and use cases
   • Common patterns
   • Related classes

3. Code examples:

   • Basic usage
   • Advanced features
   • Error handling
   • Best practices

Proposed Improvements

1. Enhanced Method Documentation

/// Starts the tracker's periodic announce loop.
///
/// This method begins sending periodic announce requests to the tracker
/// at intervals specified by the tracker's response (or defaultIntervalTime).
/// The first announce will use the [EVENT_STARTED] event type.
///
/// **Important:** This tracker must not be disposed before calling this method.
///
/// Returns `true` if the announce loop started successfully, `false` otherwise.
///
/// Throws [Exception] if the tracker has already been disposed.
///
/// Example:
/// ```dart
/// var tracker = HttpTracker(uri, infoHash);
/// var started = await tracker.start();
/// if (started) {
///   print('Tracker started successfully');
/// }
/// ```
Future<bool> start() async {
  // ... implementation ...
}

2. Class-Level Documentation

/// HTTP/HTTPS BitTorrent tracker implementation.
///
/// This class implements the HTTP/HTTPS tracker protocol as specified in
/// [BEP 0003](https://www.bittorrent.org/beps/bep_0003.html).
///
/// **Key Features:**
/// - Supports both HTTP and HTTPS trackers
/// - Automatic interval management based on tracker responses
/// - Event-based architecture for peer discovery
/// - IPv6 support (BEP 0007)
///
/// **Basic Usage:**
/// ```dart
/// var tracker = HttpTracker(
///   Uri.parse('https://tracker.example.com/announce'),
///   infoHashBuffer,
/// );
///
/// tracker.events.on<TrackerPeerEventEvent>((event) {
///   print('Received ${event.peerEvent.peers.length} peers');
/// });
///
/// await tracker.start();
/// ```
///
/// **Advanced Usage:**
/// ```dart
/// var tracker = HttpTracker(uri, infoHash, provider: customProvider);
/// tracker.enableStatistics = true;  // Optional metrics
/// await tracker.start();
/// ```
///
/// See also:
/// - [UDPTracker] for UDP tracker implementation
/// - [TorrentAnnounceTracker] for managing multiple trackers
class HttpTracker extends Tracker with HttpTrackerBase {
  // ... implementation ...
}

3. Parameter Documentation

/// Creates a new HTTP tracker instance.
///
/// [uri] - The tracker announce URL (must be http:// or https://)
/// [infoHashBuffer] - The 20-byte info hash of the torrent
/// [provider] - Optional provider for announce parameters. If null,
///   default values will be used (downloaded: 0, uploaded: 0, etc.)
///
/// Throws [ArgumentError] if infoHashBuffer is not exactly 20 bytes.
///
/// Example:
/// ```dart
/// var provider = MyAnnounceOptionsProvider();
/// var tracker = HttpTracker(
///   Uri.parse('https://tracker.example.com/announce'),
///   torrent.infoHashBuffer,
///   provider: provider,
/// );
/// ```
HttpTracker(
  Uri uri,
  Uint8List infoHashBuffer, {
  AnnounceOptionsProvider? provider,
}) : super(/* ... */);

4. Error Handling Documentation

/// Processes the tracker's HTTP response.
///
/// This method decodes the BEncode response and extracts peer information,
/// interval times, and other tracker metadata.
///
/// [data] - The raw BEncode-encoded response data from the tracker
///
/// Returns a [PeerEvent] containing peer addresses and tracker metadata.
///
/// Throws:
/// - [BEncodeDecodeException] if the response cannot be decoded
/// - [String] if the tracker returns a "failure reason"
/// - Other exceptions for network or parsing errors
///
/// Example:
/// ```dart
/// try {
///   var event = tracker.processResponseData(responseData);
///   print('Interval: ${event.interval} seconds');
///   print('Peers: ${event.peers.length}');
/// } on BEncodeDecodeException catch (e) {
///   print('Invalid response format: $e');
/// } catch (e) {
///   print('Tracker error: $e');
/// }
/// ```
@override
PeerEvent processResponseData(Uint8List data) {
  // ... implementation ...
}

5. Add README Examples

Enhance the README with more examples:

• Error handling patterns
• Custom provider implementation
• Statistics usage
• Multiple tracker management
• Scrape examples

Impact

• Severity: Low (Documentation Improvement)
• Affected: Developer experience and onboarding
• Benefits:
  • Easier API discovery
  • Better IDE support (autocomplete, hints)
  • Reduced learning curve
  • Fewer usage mistakes
  • Better maintainability

Additional Context

Good documentation helps:

• New developers understand the API
• IDE tooling provide better hints
• Automated documentation generation (dartdoc)
• API discoverability
• Reducing support questions

Related Standards

• Dart documentation conventions
• dartdoc best practices