[doc] Document the Backend::Api library

Started with the Backend::ConnectionHelper module

.jshintignore

@@ -1,3 +1,4 @@
 src/api/app/assets/javascripts/webui/application/cm2/
 src/api/vendor/assets/javascripts/*.min.js
 src/api/vendor/bundle/
+src/api/lib/backend/doc

src/api/lib/backend/.gitignore

@@ -0,0 +1 @@
+.yardoc

src/api/lib/backend/connection_helper.rb

@@ -1,22 +1,95 @@
-# API for connecting to the backend
 module Backend
+  # Module that holds the wrapping methods for http requests, are mainly used for simplify the calculation of urls.
+  #
+  # All the methods need a valid +endpoint+ to connect to, and it can be provided in two different ways:
+  # * As a single string. No processing is performed.
+  # * As an array. In this case the first element needs to be a string with placeholders that will be replaced in the order provided
+  #   starting with the second element of the array.
+  #   The placeholders have the same style as ruby symbols.
+  #     get(["/build/:project/:package/_result", "Apache", "apache2"])
+  #     # => HTTP GET "/build/Apache/apache2/_result"
+  #
+  # The +options+ hash is used for providing the params and other options available.
+  # +:params+:: Hash with the parameters to be sent as part of the query in the url.
+  #      get("/source/Apache/_meta", params: { revision: 42 })
+  #      # => HTTP GET "/source/Apache/_meta?revision=42"
+  #
+  # +:defaults+:: Hash with the default parameters values that will be merged with <tt>options[:params]</tt>.
+  #     get("/source/Apache", defaults: { cmd: :copy, revision: 1 }, params: { revision: 42, target: Nginx })
+  #     # => HTTP GET "/source/Apache?cmd=copy&revision=42&target=Nginx"
+  #
+  # +:rename+:: Hash with the pairs of params keys to rename before converting the url.
+  #     get("/source/Apache/_meta", params: { revision: 42 }, rename: { revision: :rev})
+  #     # => HTTP GET "/source/Apache/_meta?rev=42"
+  #
+  # +:accepted+:: Array with the whitelist of keys for the params.
+  #     get("/source/Apache/_meta", params: { revision: 42, fake: 2 }, accepted: [:revision, :comment])
+  #     # => HTTP GET "/source/Apache/_meta?revision=42"
+  #
+  # +:expand+:: Array of keys to expand using the same name (no [] are used).
+  #     get("/source/Apache/_meta", params: { revision: 42, package: ['pack1', 'pack2'] }, expand: [:package])
+  #     # => HTTP GET "/source/Apache/_meta?revision=42&package=pack1&package=pack2"
+  #
+  # +:data+:: In the case of +put+ or +post+ requests is the data that will be sent.
+  #
+  #
+  # +:headers+:: Hash with the headers that will be added to the request.
+  #
+
   module ConnectionHelper
-    # Performs a get action
+    # Performs a http get request to the configured OBS Backend server.
+    # @param endpoint [String, Array] Endpoit to connect to.
+    # @option options [Hash] :params The parameters to be sent as part of the query in the url.
+    # @option options [Hash] :defaults The default parameters values that will be merged with <tt>options[:params]</tt>.
+    # @option options [Hash] :rename The parameters to be sent as part of the query in the url.
+    # @option options [Array] :accepted Whitelist of keys for the params.
+    # @option options [Array] :expand Keys to expand using the same name (no [] are used).
+    # @option options [Hash] :headers The http headers that will be added to the request.
+    # @return [String] The body of the request response encoded in UTF-8.
+    # @example Few examples of use:
+    #     get("/source/Apache/_meta", params: { revision: 42, package: ['pack1', 'pack2'] }, expand: [:package])
+    #     # => HTTP GET "/source/Apache/_meta?revision=42&package=pack1&package=pack2"
     def get(endpoint, options = {})
       Backend::Connection.get(calculate_url(endpoint, options), options[:headers] || {}).body.force_encoding("UTF-8")
     end
 
-    # Performs a post action
+    # Performs a http post request to the configured OBS Backend server.
+    # @param endpoint [String, Array] Endpoit to connect to.
+    # @option options [Hash] :params The parameters to be sent as part of the query in the url.
+    # @option options [Hash] :defaults The default parameters values that will be merged with <tt>options[:params]</tt>.
+    # @option options [Hash] :rename The parameters to be sent as part of the query in the url.
+    # @option options [Array] :accepted Whitelist of keys for the params.
+    # @option options [Array] :expand Keys to expand using the same name (no [] are used).
+    # @option options [String] :data The data that will be sent in the request.
+    # @option options [Hash] :headers The http headers that will be added to the request.
+    # @return [String] The body of the request response encoded in UTF-8.
     def post(endpoint, options = {})
       Backend::Connection.post(calculate_url(endpoint, options), options[:data], options[:headers] || {}).body.force_encoding("UTF-8")
     end
 
-    # Performs a put action
+    # Performs a http put request to the configured OBS Backend server.
+    # @param endpoint [String, Array] Endpoit to connect to.
+    # @option options [Hash] :params The parameters to be sent as part of the query in the url.
+    # @option options [Hash] :defaults The default parameters values that will be merged with <tt>options[:params]</tt>.
+    # @option options [Hash] :rename The parameters to be sent as part of the query in the url.
+    # @option options [Array] :accepted Whitelist of keys for the params.
+    # @option options [Array] :expand Keys to expand using the same name (no [] are used).
+    # @option options [String] :data The data that will be sent in the request.
+    # @option options [Hash] :headers The http headers that will be added to the request.
+    # @return [String] The body of the request response encoded in UTF-8.
     def put(endpoint, options = {})
       Backend::Connection.put(calculate_url(endpoint, options), options[:data], options[:headers] || {}).body.force_encoding("UTF-8")
     end
 
-    # Performs a delete action
+    # Performs a http delete request to the configured OBS Backend server.
+    # @param endpoint [String, Array] Endpoit to connect to.
+    # @option options [Hash] :params The parameters to be sent as part of the query in the url.
+    # @option options [Hash] :defaults The default parameters values that will be merged with <tt>options[:params]</tt>.
+    # @option options [Hash] :rename The parameters to be sent as part of the query in the url.
+    # @option options [Array] :accepted Whitelist of keys for the params.
+    # @option options [Array] :expand Keys to expand using the same name (no [] are used).
+    # @option options [Hash] :headers The http headers that will be added to the request.
+    # @return [String] The body of the request response encoded in UTF-8.
     def delete(endpoint, options = {})
       Backend::Connection.delete(calculate_url(endpoint, options), options[:headers] || {}).body.force_encoding("UTF-8")
     end

src/api/lib/backend/doc/Backend.html

@@ -0,0 +1,130 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Backend
+
+    &mdash; Documentation by YARD 0.9.9
+
+</title>
+
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "Backend";
+  relpath = '';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+
+    <a href="_index.html">Index (B)</a> &raquo;
+
+
+    <span class="title">Backend</span>
+
+</div>
+
+        <div id="search">
+
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Module: Backend
+
+
+
+</h1>
+<div class="box_info">
+
+
+
+
+
+
+
+
+
+
+
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>file.rb<span class="defines">,<br />
+  test.rb,<br /> logger.rb,<br /> api/search.rb,<br /> api/server.rb,<br /> connection.rb,<br /> test/tasks.rb,<br /> api/published.rb,<br /> connection_helper.rb,<br /> api/sources/package.rb,<br /> api/sources/project.rb,<br /> api/build_results/status.rb,<br /> api/build_results/worker.rb,<br /> api/build_results/binaries.rb</span>
+</dd>
+  </dl>
+
+</div>
+
+<h2>Overview</h2><div class="docstring">
+  <div class="discussion">
+
+<p>API for accessing to the backend</p>
+
+
+  </div>
+</div>
+<div class="tags">
+
+
+</div><h2>Defined Under Namespace</h2>
+<p class="children">
+
+
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Backend/Api.html" title="Backend::Api (module)">Api</a></span>, <span class='object_link'><a href="Backend/ConnectionHelper.html" title="Backend::ConnectionHelper (module)">ConnectionHelper</a></span>
+
+
+
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Backend/Connection.html" title="Backend::Connection (class)">Connection</a></span>, <span class='object_link'><a href="Backend/File.html" title="Backend::File (class)">File</a></span>, <span class='object_link'><a href="Backend/Logger.html" title="Backend::Logger (class)">Logger</a></span>, <span class='object_link'><a href="Backend/Test.html" title="Backend::Test (class)">Test</a></span>
+
+
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+      <div id="footer">
+  Generated by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.9.
+</div>
+
+    </div>
+  </body>
+</html>

src/api/lib/backend/doc/Backend/Api.html

@@ -0,0 +1,119 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Backend::Api
+
+    &mdash; Documentation by YARD 0.9.9
+
+</title>
+
+  <link rel="stylesheet" href="../css/style.css" type="text/css" charset="utf-8" />
+
+  <link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8" />
+
+<script type="text/javascript" charset="utf-8">
+  pathId = "Backend::Api";
+  relpath = '../';
+</script>
+
+
+  <script type="text/javascript" charset="utf-8" src="../js/jquery.js"></script>
+
+  <script type="text/javascript" charset="utf-8" src="../js/app.js"></script>
+
+
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="../class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+
+    <a href="../_index.html">Index (A)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../Backend.html" title="Backend (module)">Backend</a></span></span>
+     &raquo; 
+    <span class="title">Api</span>
+
+</div>
+
+        <div id="search">
+
+    <a class="full_list_link" id="class_list_link"
+        href="../class_list.html">
+
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+
+</div>
+        <div class="clear"></div>
+      </div>
+
+      <div id="content"><h1>Module: Backend::Api
+
+
+
+</h1>
+<div class="box_info">
+
+
+
+
+
+
+
+
+
+
+
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>api/search.rb<span class="defines">,<br />
+  api/server.rb,<br /> api/published.rb,<br /> api/sources/package.rb,<br /> api/sources/project.rb,<br /> api/build_results/status.rb,<br /> api/build_results/worker.rb,<br /> api/build_results/binaries.rb</span>
+</dd>
+  </dl>
+
+</div>
+
+<h2>Defined Under Namespace</h2>
+<p class="children">
+
+
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Api/BuildResults.html" title="Backend::Api::BuildResults (module)">BuildResults</a></span>, <span class='object_link'><a href="Api/Sources.html" title="Backend::Api::Sources (module)">Sources</a></span>
+
+
+
+      <strong class="classes">Classes:</strong> <span class='object_link'><a href="Api/Published.html" title="Backend::Api::Published (class)">Published</a></span>, <span class='object_link'><a href="Api/Search.html" title="Backend::Api::Search (class)">Search</a></span>, <span class='object_link'><a href="Api/Server.html" title="Backend::Api::Server (class)">Server</a></span>
+
+
+</p>
+
+
+
+
+
+
+
+
+
+</div>
+
+      <div id="footer">
+  Generated by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.9.
+</div>
+
+    </div>
+  </body>
+</html>