From acd7bbab9713289b5f7e47a97d5133e2ee16fa80 Mon Sep 17 00:00:00 2001
From: Brian Palmer <brianp@instructure.com>
Date: Wed, 13 Jun 2012 12:49:36 -0600
Subject: [PATCH] flag the following apis as beta

adds support for flagging individual endpoints, not just resources, as
beta.

test plan: generate the api docs and verify that the tagged endpoints
have a beta message.

Change-Id: Iba815db309ee71482e1f471eaf613527cd7114ec
Reviewed-on: https://gerrit.instructure.com/11585
Reviewed-by: Simon Williams <simon@instructure.com>
Tested-by: Jenkins <jenkins@instructure.com>
---
 app/controllers/collection_items_controller.rb   |  1 +
 app/controllers/groups_controller.rb             |  2 ++
 app/controllers/users_controller.rb              | 13 +++++++------
 doc/api/fulldoc/html/css/common.css              |  3 ++-
 doc/api/method_details/html/header.erb           |  3 +++
 doc/api/method_details/html/method_signature.erb |  2 +-
 doc/api/method_details/html/setup.rb             |  1 +
 7 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/app/controllers/collection_items_controller.rb b/app/controllers/collection_items_controller.rb
index d592c6931c8..40ee3d85b92 100644
--- a/app/controllers/collection_items_controller.rb
+++ b/app/controllers/collection_items_controller.rb
@@ -17,6 +17,7 @@
 #
 
 # @API Collections
+# @beta
 #
 # Collections contain Collection Items, which are links to content. There are
 # different types of items for links to different types of data.
diff --git a/app/controllers/groups_controller.rb b/app/controllers/groups_controller.rb
index 33ec8efb8a5..ae65505b0c8 100644
--- a/app/controllers/groups_controller.rb
+++ b/app/controllers/groups_controller.rb
@@ -406,6 +406,7 @@ class GroupsController < ApplicationController
   end
 
   # @API Follow a group
+  # @beta
   #
   # Follow this group. If the current user is already following the
   # group, nothing happens. The user must have permissions to view the
@@ -439,6 +440,7 @@ class GroupsController < ApplicationController
   end
 
   # @API Un-follow a group
+  # @beta
   #
   # Stop following this group. If the current user is not already
   # following the group, nothing happens.
diff --git a/app/controllers/users_controller.rb b/app/controllers/users_controller.rb
index 275a25435d2..93b7b60c462 100644
--- a/app/controllers/users_controller.rb
+++ b/app/controllers/users_controller.rb
@@ -893,20 +893,19 @@ class UsersController < ApplicationController
     end
   end
 
-  #@API Delete a user.
+  # @API Delete a user
+  #
   # Delete a user record from Canvas.
   #
   # WARNING: This API will allow a user to delete themselves. If you do this,
   # you won't be able to make API calls or log into Canvas.
   #
   # @example_request
-  #
-  # curl https://<canvas>/api/v1/users/5 \ 
-  #   -H 'Authorization: Bearer <ACCESS_TOKEN>' \ 
-  #   -X DELETE
+  #     curl https://<canvas>/api/v1/users/5 \ 
+  #       -H 'Authorization: Bearer <ACCESS_TOKEN>' \ 
+  #       -X DELETE
   #
   # @example_response
-  #
   #   {
   #     "id":133,
   #     "login_id":"bieber@example.com",
@@ -1075,6 +1074,7 @@ class UsersController < ApplicationController
   include Api::V1::UserFollow
 
   # @API Follow a user
+  # @beta
   #
   # Follow this user. If the current user is already following the
   # target user, nothing happens. The target user must have a public profile in
@@ -1110,6 +1110,7 @@ class UsersController < ApplicationController
   end
 
   # @API Un-follow a user
+  # @beta
   #
   # Stop following this user. If the current user is not already
   # following the target user, nothing happens.
diff --git a/doc/api/fulldoc/html/css/common.css b/doc/api/fulldoc/html/css/common.css
index a794dbeee32..ef468f620e4 100644
--- a/doc/api/fulldoc/html/css/common.css
+++ b/doc/api/fulldoc/html/css/common.css
@@ -43,6 +43,7 @@ h3.beta {
   background-color: #E5E8FF;
   text-align: center;
   padding: 6px;
+  font-weight: bold;
 }
 
 #sidebar {
@@ -94,7 +95,7 @@ h3.beta {
 .syntaxhighlighter .line code { white-space: nowrap; }
 .syntaxhighlighter { overflow: auto; }
 
-.method_details h3 {
+.method_details h3.endpoint {
   font-size: 14px;
   font-weight: normal;
   font-family: Monaco, Consolas, Courier, monospace;
diff --git a/doc/api/method_details/html/header.erb b/doc/api/method_details/html/header.erb
index 973b35c52f5..fc29cbc3ce8 100644
--- a/doc/api/method_details/html/header.erb
+++ b/doc/api/method_details/html/header.erb
@@ -7,5 +7,8 @@
       <span class='defined-in'><a href="https://github.com/instructure/canvas-lms/blob/master/<%= @controller_path %>"><%= "#{@route.requirements[:controller].camelize}Controller\##{@route.requirements[:action]}" %></a></span>
     <% end %>
   </h2>
+  <% if @beta %>
+    <h3 class='beta'>BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.</h3>
+  <% end %>
   <%= yieldall %>
 </div>
diff --git a/doc/api/method_details/html/method_signature.erb b/doc/api/method_details/html/method_signature.erb
index 36b265db3e9..90853776bf1 100644
--- a/doc/api/method_details/html/method_signature.erb
+++ b/doc/api/method_details/html/method_signature.erb
@@ -1,7 +1,7 @@
 <% @routes.each do |route| %>
 <% route_path = route.segments.inject("") { |str,s| str << s.to_s }.sub(/\(\.:format\)\?/, '').sub(/\/$/, '')
    next if route_path =~ /\.json$/ %>
-<h3>
+<h3 class='endpoint'>
   <%= route.conditions[:method].to_s.upcase %> <%= route_path %>
 </h3>
 <% end %>
diff --git a/doc/api/method_details/html/setup.rb b/doc/api/method_details/html/setup.rb
index 99a273bd119..50b644c2e8b 100644
--- a/doc/api/method_details/html/setup.rb
+++ b/doc/api/method_details/html/setup.rb
@@ -26,6 +26,7 @@ def header
   @subtopic = (object.tag('subtopic') || object.parent.tag('API')).text
   route = @routes.first
   @method_link = "method.#{route.requirements[:controller]}.#{route.requirements[:action]}"
+  @beta = object.tag('beta') || object.parent.tag('beta')
   erb(:header)
 end