docs(geodata): clarify ServiceException #255

dart/geodata/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 NOTE: [geodata version 1.4.0](https://github.com/navibyte/geospatial/milestone/7) currently under development (1.4.0-dev.0).
 
+🛠 Maintenance:
+* [Clarify ServiceException docs and add equality / hashCode methods #255](https://github.com/navibyte/geospatial/issues/255)
+
 ## 1.3.0
 
 ✨ New (2024-11-10): The stable version 1.3.0 with some refactoring (the

dart/geodata/lib/src/common/service/service_exception.dart

@@ -1,25 +1,45 @@
-// Copyright (c) 2020-2023 Navibyte (https://navibyte.com). All rights reserved.
+// Copyright (c) 2020-2024 Navibyte (https://navibyte.com). All rights reserved.
 // Use of this source code is governed by a “BSD-3-Clause”-style license that is
 // specified in the LICENSE file.
 //
 // Docs: https://github.com/navibyte/geospatial
 
-/// An exception that could occur when accessing some service.
-class ServiceException<T> implements Exception {
-  /// Create an exception.
+import 'package:meta/meta.dart';
+
+/// An exception that may occur when accessing app business logic or a service.
+///
+/// The required [failure] property provides an app specific failure of the type
+/// [T].
+///
+/// An optional source for the exception is provided by [cause] and [trace].
+@immutable
+class ServiceException<T extends Object> implements Exception {
+  /// Create an exception with [failure], and optional [cause] and [trace].
   const ServiceException(this.failure, {this.cause, this.trace});
 
-  /// The failure as an object of [T].
+  /// The app specific failure as an object of [T].
   final T failure;
 
   /// An optional source that caused the exception.
   ///
-  /// Could be another exception or error instance, or a String object.
+  /// This could be for example another exception, an error instance or a String
+  /// object.
   final Object? cause;
 
-  /// An optional stack trace that is accociated to an optional [cause].
+  /// An optional stack trace that is accociated with an optional [cause].
   final StackTrace? trace;
 
   @override
-  String toString() => failure.toString();
+  String toString() => '$failure${cause != null ? " ($cause)" : ""}';
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      (other is ServiceException<T> &&
+          failure == other.failure &&
+          cause == other.cause &&
+          trace == other.trace);
+
+  @override
+  int get hashCode => Object.hash(failure, cause, trace);
 }