SONAR-6438 Sanitize description of WS sections (#985)

server/sonar-server/src/main/java/org/sonar/server/authentication/ws/AuthenticationWs.java

@@ -28,7 +28,7 @@ public class AuthenticationWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/authentication");
-    controller.setDescription("Check authentication credentials");
+    controller.setDescription("Check authentication credentials.");
 
     defineValidateAction(controller);
 

server/sonar-server/src/main/java/org/sonar/server/ce/ws/CeWs.java

@@ -35,7 +35,7 @@ public class CeWs implements WebService {
   public void define(Context context) {
     NewController controller = context
       .createController(ENDPOINT)
-      .setDescription("Compute Engine");
+      .setDescription("Get information on Compute Engine tasks.");
     for (CeWsAction action : actions) {
       action.define(controller);
     }

server/sonar-server/src/main/java/org/sonar/server/component/ws/ComponentsWs.java

@@ -39,7 +39,7 @@ public class ComponentsWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/components")
       .setSince("4.2")
-      .setDescription("Components management");
+      .setDescription("Get information about a component (file, directory, project, ...) and its ancestors or children.");
 
     for (ComponentsWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/component/ws/EventsWs.java

@@ -27,7 +27,7 @@ public class EventsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/events");
-    controller.setDescription("Project's events management");
+    controller.setDescription("Manage project events.");
     controller.setSince("2.6");
 
     defineIndexAction(controller);

server/sonar-server/src/main/java/org/sonar/server/component/ws/ResourcesWs.java

@@ -30,7 +30,7 @@ public class ResourcesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/resources")
-      .setDescription("Former components web service")
+      .setDescription("Former components web api. Deprecated since 5.4.")
       .setSince("2.10");
 
     defineIndexAction(controller);

server/sonar-server/src/main/java/org/sonar/server/config/ws/PropertiesWs.java

@@ -27,7 +27,7 @@ public class PropertiesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/properties");
-    controller.setDescription("Properties management");
+    controller.setDescription("Manage global and project properties.");
     controller.setSince("2.6");
 
     defineIndexAction(controller);

server/sonar-server/src/main/java/org/sonar/server/duplication/ws/DuplicationsWs.java

@@ -33,7 +33,7 @@ public class DuplicationsWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/duplications")
       .setSince("4.4")
-      .setDescription("Display duplications information");
+      .setDescription("Get duplication information for a project.");
     showAction.define(controller);
     controller.done();
   }

server/sonar-server/src/main/java/org/sonar/server/issue/filter/IssueFilterWs.java

@@ -33,7 +33,7 @@ public class IssueFilterWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/issue_filters")
       .setSince("4.2")
-      .setDescription("Issue Filters management");
+      .setDescription("Get details on existing issue filters/saved issue searches.");
     for (IssueFilterWsAction action : actions) {
       action.define(controller);
     }

server/sonar-server/src/main/java/org/sonar/server/issue/ws/IssuesWs.java

@@ -46,7 +46,7 @@ public class IssuesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(API_ENDPOINT);
-    controller.setDescription("Coding rule issues");
+    controller.setDescription("Read and update issues.");
     controller.setSince("3.6");
     for (IssuesWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/language/ws/LanguageWs.java

@@ -35,7 +35,7 @@ public class LanguageWs implements WebService {
   @Override
   public void define(Context context) {
     NewController languages = context.createController("api/languages")
-      .setDescription("Programming languages")
+      .setDescription("Get the list of programming languages supported in this instance.")
       .setSince("5.1");
 
     list.define(languages);

server/sonar-server/src/main/java/org/sonar/server/measure/custom/ws/CustomMeasuresWs.java

@@ -33,7 +33,7 @@ public class CustomMeasuresWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(ENDPOINT)
-      .setDescription("Custom measures management")
+      .setDescription("Manage custom measures for a project. See also api/metrics.")
       .setSince("5.2");
 
     for (CustomMeasuresWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/measure/ws/MeasuresWs.java

@@ -33,7 +33,7 @@ public class MeasuresWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController(MeasuresWsParameters.CONTROLLER_MEASURES)
       .setSince("5.4")
-      .setDescription("Measures search");
+      .setDescription("Get components or children with specified measures.");
 
     for (MeasuresWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/measure/ws/TimeMachineWs.java

@@ -30,7 +30,7 @@ public class TimeMachineWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/timemachine")
-      .setDescription("Get a list of past measures")
+      .setDescription("Get project measure data from past analyses.")
       .setSince("2.10");
 
     defineSystemAction(controller);

server/sonar-server/src/main/java/org/sonar/server/metric/ws/MetricsWs.java

@@ -34,7 +34,7 @@ public class MetricsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(ENDPOINT);
-    controller.setDescription("Metrics management");
+    controller.setDescription("Get information on automatic metrics, and manage custom metrics. See also api/custom_measures.");
     controller.setSince("2.6");
 
     for (MetricsWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/permission/ws/PermissionsWs.java

@@ -33,7 +33,7 @@ public class PermissionsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(CONTROLLER);
-    controller.setDescription("Permissions management");
+    controller.setDescription("Manage permission templates, and the granting and revoking of permissions at the global and project levels.");
     controller.setSince("3.7");
 
     for (PermissionsWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/platform/ws/SystemWs.java

@@ -31,7 +31,8 @@ public class SystemWs implements WebService {
 
   @Override
   public void define(Context context) {
-    NewController controller = context.createController("api/system");
+    NewController controller = context.createController("api/system")
+      .setDescription("Get system details, and perform some management actions, such as restarting, and initiating a database migration (as part of a system upgrade).");
 
     for (SystemWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/plugins/ws/PluginsWs.java

@@ -34,7 +34,7 @@ public class PluginsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/plugins");
-    controller.setDescription("Plugin management")
+    controller.setDescription("Manage the plugins on the server, including installing, uninstalling, and upgrading.")
       .setSince("5.2");
 
     for (PluginsWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/project/ws/ProjectsWs.java

@@ -40,7 +40,7 @@ public class ProjectsWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController(ENDPOINT)
       .setSince("2.10")
-      .setDescription("Projects management");
+      .setDescription("Manage project existence.");
 
     defineIndexAction(controller);
     defineCreateAction(controller);

server/sonar-server/src/main/java/org/sonar/server/qualitygate/ws/QGatesWs.java

@@ -51,7 +51,7 @@ public class QGatesWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/qualitygates")
       .setSince("4.3")
-      .setDescription("This service manages quality gates, including conditions and project association");
+      .setDescription("Manage quality gates, including conditions and project association.");
 
     for (QGateWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/qualityprofile/ws/QProfilesWs.java

@@ -43,7 +43,7 @@ public class QProfilesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(API_ENDPOINT)
-      .setDescription("Quality Profiles")
+      .setDescription("Manage quality profiles.")
       .setSince("4.4");
 
     ruleActivationActions.define(controller);

server/sonar-server/src/main/java/org/sonar/server/rule/ws/RulesWs.java

@@ -33,7 +33,7 @@ public class RulesWs implements WebService {
   public void define(Context context) {
     NewController controller = context
       .createController("api/rules")
-      .setDescription("Coding rules");
+      .setDescription("Get and update some details of automatic rules, and manage custom rules.");
 
     for (RulesWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/source/ws/SourcesWs.java

@@ -33,7 +33,7 @@ public class SourcesWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/sources")
       .setSince("4.2")
-      .setDescription("Display sources information");
+      .setDescription("Get details on source files. See also api/tests.");
     for (SourcesWsAction action : actions) {
       action.define(controller);
     }

server/sonar-server/src/main/java/org/sonar/server/test/ws/TestsWs.java

@@ -33,7 +33,7 @@ public class TestsWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/tests")
       .setSince("4.4")
-      .setDescription("Tests management. Deprecated since 5.6");
+      .setDescription("Get details on test files. See also api/sources. Deprecated since 5.6.");
 
     for (TestsWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/user/ws/FavoritesWs.java

@@ -27,7 +27,7 @@ public class FavoritesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/favorites");
-    controller.setDescription("User's favorites management");
+    controller.setDescription("Manage user favorites.");
     controller.setSince("2.6");
 
     defineIndexAction(controller);

server/sonar-server/src/main/java/org/sonar/server/user/ws/UserPropertiesWs.java

@@ -27,7 +27,7 @@ public class UserPropertiesWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/user_properties");
-    controller.setDescription("User properties management");
+    controller.setDescription("Manage user properties.");
     controller.setSince("2.6");
 
     defineIndexAction(controller);

server/sonar-server/src/main/java/org/sonar/server/user/ws/UsersWs.java

@@ -33,7 +33,7 @@ public class UsersWs implements WebService {
   public void define(Context context) {
     NewController controller = context.createController("api/users")
       .setSince("3.6")
-      .setDescription("Users management");
+      .setDescription("Manage users.");
 
     for (UsersWsAction action : actions) {
       action.define(controller);

server/sonar-server/src/main/java/org/sonar/server/usergroups/ws/UserGroupsWs.java

@@ -32,7 +32,7 @@ public class UserGroupsWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController("api/user_groups")
-      .setDescription("User groups management")
+      .setDescription("Manage user groups.")
       .setSince("5.2");
 
     for (UserGroupsWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/usertoken/ws/UserTokensWs.java

@@ -33,8 +33,7 @@ public class UserTokensWs implements WebService {
   @Override
   public void define(Context context) {
     NewController controller = context.createController(CONTROLLER)
-      .setDescription("User token management. To enhance security, tokens can be used to take the place " +
-        "of user credentials in analysis configuration. A token can be revoked at any time.")
+      .setDescription("List, create, and delete a user's access tokens.")
       .setSince("5.3");
 
     for (UserTokensWsAction action : actions) {

server/sonar-server/src/main/java/org/sonar/server/ws/WebServicesWs.java

@@ -44,7 +44,7 @@ public class WebServicesWs implements WebService {
     NewController controller = context
       .createController("api/webservices")
       .setSince("4.2")
-      .setDescription("List web services");
+      .setDescription("Get information on the web api supported on this instance.");
     defineList(context, controller);
     defineResponseExample(context, controller);
     controller.done();

server/sonar-server/src/main/resources/org/sonar/server/ws/list-example.json

@@ -44,7 +44,7 @@
     },
     {
       "path": "api/webservices",
-      "description": "List web services",
+      "description": "Get information on the web api supported on this instance.",
       "since": "4.2",
       "actions": [
         {

server/sonar-server/src/test/resources/org/sonar/server/ws/WebServicesWsTest/list_including_internals.json

@@ -44,7 +44,7 @@
   },
   {
     "path": "api/webservices",
-    "description": "List web services",
+    "description": "Get information on the web api supported on this instance.",
     "since": "4.2",
     "actions": [
       {