[service] Improve doc

agama-project · Apr 27, 2023 · d86b948 · d86b948
1 parent 3a29e94
commit d86b948
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 5 deletions.
diff --git a/service/lib/agama/dbus.rb b/service/lib/agama/dbus.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) [2022] SUSE LLC
+# Copyright (c) [2022-2023] SUSE LLC
 #
 # All Rights Reserved.
 #

diff --git a/service/lib/agama/dbus/interfaces/issues.rb b/service/lib/agama/dbus/interfaces/issues.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Copyright (c) [2022] SUSE LLC
+# Copyright (c) [2023] SUSE LLC
 #
 # All Rights Reserved.
 #

diff --git a/service/lib/agama/issue.rb b/service/lib/agama/issue.rb
@@ -20,7 +20,20 @@
 # find current contact information at www.suse.com.
 
 module Agama
-  # Represents an issue
+  # This class represents an issue in Agama
+  #
+  # An issue is used for notifying about some unexpected or problematic situation, for example, to
+  # indicate that there is no device for installing the system.
+  #
+  # Issues have a description, details, source and severity:
+  # * Description: describes the issue, typically with a single sentence.
+  # * Details: provides more details about the problem. It is useful to report the output of a
+  #   command failure.
+  # * Source: indicates the source of the problem. In Agama, the issues usually comes from some
+  #   unexpected situation in the system (e.g., missing device, etc) or from a wrong config (e.g.,
+  #   missing user, etc).
+  # * Severity: sets the severity of the issue. For now, issues could have warn or error severity.
+  #   Error severity indicates that the installation cannot start.
   class Issue
     # Description of the issue
     #
@@ -48,7 +61,7 @@ module Source
       CONFIG = :config
     end
 
-    # Defines different severities
+    # Defines different severity levels
     module Severity
       WARN = :warn
       ERROR = :error

diff --git a/service/lib/agama/with_issues.rb b/service/lib/agama/with_issues.rb
@@ -20,7 +20,7 @@
 # find current contact information at www.suse.com.
 
 module Agama
-  # Mixin for managing issues
+  # Mixin for managing issues, see {Issue}
   module WithIssues
     # The list of current issues
     #