Merge pull request #4031 from mdeniz/document_backend_api

Developer documentation for the Backend library using YARD

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

@@ -1,47 +1,57 @@
-# API for accessing to the backend
 module Backend
   module Api
     module BuildResults
+      # Class that connect to endpoints related to binaries
       class Binaries
         extend Backend::ConnectionHelper
 
         # Returns a file list of binaries
-        def self.files(project, repository, arch, package)
-          get(["/build/:project/:repository/:arch/:package", project, repository, arch, 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
-        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
-        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
-        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
-        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
-        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
-        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

@@ -1,34 +1,41 @@
-# API for accessing to the backend
 module Backend
   module Api
     module BuildResults
+      # Class that connect to endpoints related to status of builds
       class Status
         extend Backend::ConnectionHelper
 
         # Returns a chunk of the build's log
-        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
-        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
-        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
-        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 log's size for a build
-        def self.build_problems(project)
-          get(["/build/:project/_result", project], params: { view: :status, code: [:failed, :broken, :unresolvable] }, expand: [:code])
+        # Returns the the problems for a build
+        # @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

@@ -1,11 +1,12 @@
-# API for accessing to the backend
 module Backend
   module Api
     module BuildResults
+      # Class that connect to endpoints related to the workers
       class Worker
         extend Backend::ConnectionHelper
 
         # Returns the worker status
+        # @return [String]
         def self.status
           get('/build/_workerstatus')
         end

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

@@ -1,12 +1,13 @@
-# API for accessing to the backend
 module Backend
   module Api
+    # Class that connect to endpoints related to the published repositories
     class Published
       extend Backend::ConnectionHelper
 
       # Returns the download url for a repository
-      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

@@ -1,13 +1,14 @@
-# API for searching in the backend
 module Backend
   module Api
+    # Class that connect to endpoints related to the search
     class Search
       extend Backend::ConnectionHelper
 
       # Performs a search of the binary in a project list
-      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

@@ -1,35 +1,44 @@
-# API for accessing to the backend
 module Backend
   module Api
+    # Class that connect to global endpoints of the OBS Backend server
+
     class Server
       extend Backend::ConnectionHelper
 
-      # Returns the notification payload
-      def self.notification_payload(notification)
-        get(["/notificationpayload/:notification", notification])
+      # JSON payload of a notification by Id.
+      # @return [String]
+      def self.notification_payload(notification_id)
+        get(["/notificationpayload/:notification", notification_id])
       end
 
-      # Deletes the notification payload
-      def self.delete_notification_payload(notification)
-        delete(["/notificationpayload/:notification", notification])
+      # Deletes the payload of the notification by Id.
+      # @return [String]
+      def self.delete_notification_payload(notification_id)
+        delete(["/notificationpayload/:notification", notification_id])
       end
 
-      # It writes the configuration
+      # It writes the configuration of the server
+      # @return [String]
       def self.write_configuration(configuration)
         put('/configuration', data: configuration)
       end
 
-      # Returns the latest notifications specifying a starting point
-      def self.last_notifications(start)
-        get("/lastnotifications", params: { start: start, block: 1 })
+      # Latest notifications specifying a starting point
+      # @param starting_point [Integer]
+      # @return [String] Last notifications
+      def self.last_notifications(starting_point)
+        get("/lastnotifications", params: { start: starting_point, block: 1 })
       end
 
       # Notifies a certain plugin with the payload
-      def self.notify_plugin(plugin, payload)
-        post(["/notify_plugins/:plugin", plugin], data: Yajl::Encoder.encode(payload), headers: { 'Content-Type' => 'application/json' })
+      # @param plugin_id [String]
+      # @return [String]
+      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 backend
+      # Pings the root of the source repository server
+      # @return [String] Hello message from the server
       def self.root
         get('/')
       end