Merge branch 'tle-update-audit-event-service-doc' into 'master'

Fix param type and name order in doc

See merge request gitlab-org/gitlab!25777

app/services/audit_event_service.rb

@@ -3,14 +3,13 @@
 class AuditEventService
   # Instantiates a new service
   #
-  # @param author [User] the user who authors the change
-  # @param entity [Object] an instance of either Project/Group/User type. This
-  #   param is also used to determine at which level the audit events are
-  #   shown.
-  #   - Project: events are visible at Project level
-  #   - Group: events are visible at Group level
+  # @param [User] author the user who authors the change
+  # @param [User, Project, Group] entity the scope which audit event belongs to
+  #   This param is also used to determine the visibility of the audit event.
+  #   - Project: events are visible at Project and Instance level
+  #   - Group: events are visible at Group and Instance level
   #   - User: events are visible at Instance level
-  # @param details [Hash] details to be added to audit event
+  # @param [Hash] details extra data of audit event
   #
   # @return [AuditEventService]
   def initialize(author, entity, details = {})
@@ -21,7 +20,7 @@ class AuditEventService
 
   # Builds the @details attribute for authentication
   #
-  # This uses the @author as the target object being changed
+  # This uses the @author as the target object being audited
   #
   # @return [AuditEventService]
   def for_authentication

ee/app/services/ee/audit_event_service.rb

@@ -7,7 +7,8 @@ module EE
 
     # Builds the @details attribute for member
     #
-    # @param member [Member] the member whom is changed
+    # @param [Member] member object being audited
+    #
     # @return [AuditEventService]
     def for_member(member)
       action = @details[:action]
@@ -66,7 +67,7 @@ module EE
     # This expects [String] :action of :destroy, :create, :update to be
     #   specified in @details attribute
     #
-    # @param group_link [ProjectGroupLink] the project group link being changed
+    # @param [ProjectGroupLink] group_link object being audited
     #
     # @return [AuditEventService]
     def for_project_group_link(group_link)
@@ -129,8 +130,8 @@ module EE
 
     # Creates an event record in DB
     #
-    # @return [nil] if audit events is not enabled
-    # @return [SecurityEvent] if record is persisted
+    # @return [SecurityEvent, nil] if record is persisted or nil if audit events
+    #   features are not enabled
     def unauth_security_event
       return unless audit_events_enabled?
 
@@ -147,11 +148,11 @@ module EE
 
     # Builds the @details attribute for user
     #
-    # This uses the [User] @entity as the target object being changed
+    # This uses the [User] @entity as the target object being audited
     #
-    # @param full_path [String] required if it is different from the User model
-    #   in @entity. This is for backward compatability and this parameter will
-    #   be dropped after all of these incorrect usages are removed.
+    # @param [String] full_path required if it is different from the User model
+    #   in @entity. This is for backward compatability and will be dropped after
+    #   all of these incorrect usages are removed.
     #
     # @return [AuditEventService]
     def for_user(full_path = @entity.full_path)
@@ -160,7 +161,7 @@ module EE
 
     # Builds the @details attribute for project
     #
-    # This uses the [Project] @entity as the target object being changed
+    # This uses the [Project] @entity as the target object being audited
     #
     # @return [AuditEventService]
     def for_project
@@ -169,7 +170,7 @@ module EE
 
     # Builds the @details attribute for group
     #
-    # This uses the [Group] @entity as the target object being changed
+    # This uses the [Group] @entity as the target object being audited
     #
     # @return [AuditEventService]
     def for_group