[doc] Fix documentation for Backend and Backend::Connection

and add some description to Backend::Test, Backend::Test::Tasks,
Backend::Logger. Also reduce documentation comments about params
introduced in the other commits

src/api/app/models/owner.rb

@@ -96,7 +96,7 @@ def self.find_assignees(rootproject, binary_name, limit = 1, devel = true, filte
     deepest = (limit < 0)
 
     # binary search via all projects
-    data = Xmlhash.parse(Backend::Api::Search.binary(projects, binary_name))
+    data = Xmlhash.parse(Backend::Api::Search.binary(projects.map(&:name), binary_name))
     # found binary package?
     return [] if data["matches"].to_i.zero?
 

src/api/lib/backend/api/build_results/binaries.rb

@@ -6,73 +6,52 @@ class Binaries
         extend Backend::ConnectionHelper
 
         # Returns a file list of binaries
-        # @param project [String] Name of the project.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @param package [String] Name of the package.
-        # @return [String] The XML with the binary files list
-        def self.files(project, repository, architecture, package)
-          get(["/build/:project/:repository/:architecture/:package", project, repository, architecture, package])
+        # @return [String]
+        def self.files(project_name, repository_name, architecture_name, package_name)
+          get(["/build/:project/:repository/:architecture/:package", project_name, repository_name, architecture_name, package_name])
         end
 
         # Returns the jobs history for a project
-        # @param project [String] Name of the project.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The XML with the job history
-        def self.job_history(project, repository, architecture)
-          get(["/build/:project/:repository/:architecture/_jobhistory", project, repository, architecture], params: { code: :lastfailures })
+        # @return [String]
+        def self.job_history(project_name, repository_name, architecture_name)
+          get(["/build/:project/:repository/:architecture/_jobhistory", project_name, repository_name, architecture_name],
+              params: { code: :lastfailures })
         end
 
-        # Returns the download url for a file of a package
-        # @param project [String] Name of the project.
-        # @param repository [String] Name of the repository.
-        # @param package [String] Name of the package.
-        # @param architecture [String] Name of the architecture.
-        # @param file [String] Name of the file.
-        # @return [String] The published path for the binary file in an XML
-        def self.download_url_for_file(project, repository, package, architecture, file)
-          get(["/build/:project/:repository/:architecture/:package/:file", project, repository, architecture, package, file],
+        # Returns the download url (published path) for a file of a package
+        # @return [String]
+        def self.download_url_for_file(project_name, repository_name, package_name, architecture_name, file_name)
+          get(["/build/:project/:repository/:architecture/:package/:file", project_name, repository_name, architecture_name, package_name, file_name],
               params: { view: :publishedpath })
         end
 
         # Returns the RPMlint log
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The content of the rmplint.log file
-        def self.rpmlint_log(project, package, repository, architecture)
-          get(["/build/:project/:repository/:architecture/:package/rpmlint.log", project, repository, architecture, package])
+        # @return [String]
+        def self.rpmlint_log(project_name, package_name, repository_name, architecture_name)
+          get(["/build/:project/:repository/:architecture/:package/rpmlint.log", project_name, repository_name, architecture_name, package_name])
         end
 
         # Returns the build dependency information
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The XML with the build dependency information
-        def self.build_dependency_info(project, package, repository, architecture)
-          get(["/build/:project/:repository/:architecture/_builddepinfo", project, repository, architecture],
-              params: { package: package, view: :pkgnames })
+        # @return [String]
+        def self.build_dependency_info(project_name, package_name, repository_name, architecture_name)
+          get(["/build/:project/:repository/:architecture/_builddepinfo", project_name, repository_name, architecture_name],
+              params: { package: package_name, view: :pkgnames })
         end
 
         # Returns the available binaries for the project
-        # @param project [String] Name of the project.
-        # @return [String] The XML with the list of available binaries
-        def self.available_in_project(project)
-          transform_binary_packages_response(get(["/build/:project/_availablebinaries", project]))
+        # @return [Hash]
+        def self.available_in_project(project_name)
+          transform_binary_packages_response(get(["/build/:project/_availablebinaries", project_name]))
         end
 
         # Returns the available binaries for the repositories given
-        # @param project [String] Name of the project.
-        # @param urls [Array] Urls of repositories.
-        # @param repositories [Array] Paths of local repositories in the form of project/repository.
-        # @return [String] The XML with the list of available binaries
-        def self.available_in_repositories(project, urls, repositories)
-          return {} if repositories.empty? && urls.empty?
-          transform_binary_packages_response(get(["/build/:project/_availablebinaries", project],
-                                                 params: { url: urls, path: repositories }, expand: [:url, :path]))
+        # @param repository_urls [Array] Absolute urls of repositories.
+        # @param repository_paths [Array] Paths of local repositories in the form of project/repository.
+        # @return [Hash]
+        def self.available_in_repositories(project_name, repository_urls, repository_paths)
+          return {} if repository_paths.empty? && repository_urls.empty?
+          transform_binary_packages_response(get(["/build/:project/_availablebinaries", project_name],
+                                                 params: { url: repository_urls, path: repository_paths }, expand: [:url, :path]))
         end
 
         # TODO: Move this method that transforms the output into another module

src/api/lib/backend/api/build_results/status.rb

@@ -6,53 +6,36 @@ class Status
         extend Backend::ConnectionHelper
 
         # Returns a chunk of the build's log
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @param starting [Integer] Starting line.
-        # @param ending [Integer] Ending line.
-        # @return [String] The chunk of the build log file
-        def self.log_chunk(project, package, repository, architecture, starting, ending)
-          endpoint = ["/build/:project/:repository/:architecture/:package/_log", project, repository, architecture, package]
-          get(endpoint, params: { nostream: 1, start: starting.to_i, end: ending.to_i })
+        # @return [String]
+        def self.log_chunk(project_name, package_name, repository_name, architecture_name, starting_line, ending_line)
+          endpoint = ["/build/:project/:repository/:architecture/:package/_log", project_name, repository_name, architecture_name, package_name]
+          get(endpoint, params: { nostream: 1, start: starting_line.to_i, end: ending_line.to_i })
         end
 
         # Returns the job status of a build
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The XML with the status of job for a build
-        def self.job_status(project, package, repository, architecture)
-          get(["/build/:project/:repository/:architecture/:package/_jobstatus", project, repository, architecture, package])
+        # @return [String]
+        def self.job_status(project_name, package_name, repository_name, architecture_name)
+          get(["/build/:project/:repository/:architecture/:package/_jobstatus", project_name, repository_name, architecture_name, package_name])
         end
 
         # Returns the result view for a build
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The XML with the result for a build
-        def self.build_result(project, package, repository, architecture)
-          get(["/build/:project/_result", project], params: { view: :status, package: package, arch: architecture, repository: repository })
+        # @return [String]
+        def self.build_result(project_name, package_name, repository_name, architecture_name)
+          get(["/build/:project/_result", project_name],
+              params: { view: :status, package: package_name, arch: architecture_name, repository: repository_name })
         end
 
         # Returns the log's size for a build
-        # @param project [String] Name of the project.
-        # @param package [String] Name of the package.
-        # @param repository [String] Name of the repository.
-        # @param architecture [String] Name of the architecture.
-        # @return [String] The size of the build log file
-        def self.build_log_size(project, package, repository, architecture)
-          get(["/build/:project/:repository/:architecture/:package/_log", project, repository, architecture, package], params: { view: :entry })
+        # @return [String]
+        def self.build_log_size(project_name, package_name, repository_name, architecture_name)
+          get(["/build/:project/:repository/:architecture/:package/_log", project_name, repository_name, architecture_name, package_name],
+              params: { view: :entry })
         end
 
         # Returns the the problems for a build
-        # @param project [String] Name of the project.
-        # @return [String] The XML with the list of problems
-        def self.build_problems(project)
-          get(["/build/:project/_result", project], params: { view: :status, code: [:failed, :broken, :unresolvable] }, expand: [:code])
+        # @return [String]
+        def self.build_problems(project_name)
+          get(["/build/:project/_result", project_name], params: { view: :status, code: [:failed, :broken, :unresolvable] }, expand: [:code])
         end
       end
     end

src/api/lib/backend/api/build_results/worker.rb

@@ -6,7 +6,7 @@ class Worker
         extend Backend::ConnectionHelper
 
         # Returns the worker status
-        # @return [String] XML with the status of the workers.
+        # @return [String]
         def self.status
           get('/build/_workerstatus')
         end

src/api/lib/backend/api/published.rb

@@ -5,11 +5,9 @@ class Published
       extend Backend::ConnectionHelper
 
       # Returns the download url for a repository
-      # @param project [String] Projects name that owns the repository.
-      # @param repository [String] Name of the repository.
-      # @return [String] XML with the published path for the repository provided
-      def self.download_url_for_repository(project, repository)
-        get(['/published/:project/:repository', project, repository], params: { view: :publishedpath })
+      # @return [String]
+      def self.download_url_for_repository(project_name, repository_name)
+        get(['/published/:project/:repository', project_name, repository_name], params: { view: :publishedpath })
       end
     end
   end

src/api/lib/backend/api/search.rb

@@ -5,12 +5,10 @@ class Search
       extend Backend::ConnectionHelper
 
       # Performs a search of the binary in a project list
-      # @param projects [Array of Projects] List of projects where to perform the search in.
-      # @param name [String] Name of the binary to look for.
-      # @return [String] XML  with the binaries collection.
-      def self.binary(projects, name)
-        project_list = projects.map { |project| "@project='#{CGI.escape(project.name)}'" }.join('+or+')
-        post("/search/published/binary/id?match=(@name='#{CGI.escape(name)}'+and+(#{project_list}))")
+      # @return [String]
+      def self.binary(project_names, binary_name)
+        project_list = project_names.map { |project_name| "@project='#{CGI.escape(project_name)}'" }.join('+or+')
+        post("/search/published/binary/id?match=(@name='#{CGI.escape(binary_name)}'+and+(#{project_list}))")
       end
     end
   end

src/api/lib/backend/api/server.rb

@@ -6,45 +6,38 @@ class Server
       extend Backend::ConnectionHelper
 
       # JSON payload of a notification by Id.
-      # @param notification [Integer] Notification identifier.
-      # @return [String] The JSON encoded structure, depending on the event that
-      #   created the notification it will have different payload keys.
-      def self.notification_payload(notification)
-        get(["/notificationpayload/:notification", notification])
+      # @return [String]
+      def self.notification_payload(notification_id)
+        get(["/notificationpayload/:notification", notification_id])
       end
 
       # Deletes the payload of the notification by Id.
-      # @param notification [Integer] Notification identifier.
       # @return [String]
-      def self.delete_notification_payload(notification)
-        delete(["/notificationpayload/:notification", notification])
+      def self.delete_notification_payload(notification_id)
+        delete(["/notificationpayload/:notification", notification_id])
       end
 
       # It writes the configuration of the server
-      # @param configuration [String] The content to write in the configuration.
       # @return [String]
       def self.write_configuration(configuration)
         put('/configuration', data: configuration)
       end
 
       # Latest notifications specifying a starting point
-      # @param start [Integer] Starting point for retrieveing the latest notifications.
+      # @param starting_point [Integer]
       # @return [String] Last notifications
-      def self.last_notifications(start)
-        get("/lastnotifications", params: { start: start, block: 1 })
+      def self.last_notifications(starting_point)
+        get("/lastnotifications", params: { start: starting_point, block: 1 })
       end
 
       # Notifies a certain plugin with the payload
-      # @param plugin [String] Plugin identifier.
-      # @param payload [Object] Payload to be encoded in JSON.
+      # @param plugin_id [String]
       # @return [String]
-      def self.notify_plugin(plugin, payload)
-        post(["/notify_plugins/:plugin", plugin], data: Yajl::Encoder.encode(payload), headers: { 'Content-Type' => 'application/json' })
+      def self.notify_plugin(plugin_id, payload)
+        post(["/notify_plugins/:plugin", plugin_id], data: Yajl::Encoder.encode(payload), headers: { 'Content-Type' => 'application/json' })
       end
 
       # Pings the root of the source repository server
-      # @example Sample of the message
-      #     <hello name="Source Repository Server" repoid="620451873" />
       # @return [String] Hello message from the server
       def self.root
         get('/')