From a98e5a3e37fe5e6fb7b86eeec83295a27c444abe Mon Sep 17 00:00:00 2001
From: Simon Brandhof <simon.brandhof@sonarsource.com>
Date: Sun, 14 Jan 2018 20:36:39 +0100
Subject: [PATCH] SONAR-10052 Improve documentation of quality profile DTOs

---
 .../db/qualityprofile/OrgQProfileDto.java     | 21 ++++++++++-
 .../db/qualityprofile/RulesProfileDto.java    | 35 ++++++++++++++++++-
 2 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/OrgQProfileDto.java b/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/OrgQProfileDto.java
index e9e7e4a5e10..bbe42576dff 100644
--- a/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/OrgQProfileDto.java
+++ b/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/OrgQProfileDto.java
@@ -23,13 +23,32 @@ import javax.annotation.CheckForNull;
 import javax.annotation.Nullable;
 
 /**
- * Represents the table "org_qprofiles"
+ * Maps the table "org_qprofiles", which represents the profiles
+ * available in an organization.
+ *
+ * Extracting organizations from table "rules_profiles"
+ * allows to optimize storage and synchronization of built-in
+ * profiles by implementing an alias mechanism. A built-in profile
+ * is stored once in table "rules_profiles" and is referenced
+ * multiple times in table "org_qprofiles".
+ * User profiles are not shared across organizations, then one row
+ * in "rules_profiles" is referenced by a single row in
+ * "org_qprofiles".
  */
 public class OrgQProfileDto {
 
   private String uuid;
+
+  /**
+   * UUID of organization. Not null.
+   */
   private String organizationUuid;
+
+  /**
+   * UUID of referenced row in table "rules_profiles". Not null.
+   */
   private String rulesProfileUuid;
+
   private String parentUuid;
   private Long lastUsed;
   private Long userUpdatedAt;
diff --git a/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/RulesProfileDto.java b/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/RulesProfileDto.java
index 59ded3e57ec..d7532445833 100644
--- a/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/RulesProfileDto.java
+++ b/server/sonar-db-dao/src/main/java/org/sonar/db/qualityprofile/RulesProfileDto.java
@@ -23,15 +23,48 @@ import java.util.Date;
 import org.sonar.core.util.UtcDateUtils;
 
 /**
- * Represents the table "rules_profiles"
+ * Maps the table "rules_profiles", which represents
+ * a group of active rules.
+ *
+ * Can be:
+ * - a built-in profile, referenced by multiple organizations
+ *   through table "org_qprofiles".
+ * - a profile created by user and referenced by one, and only one,
+ *   organization in the table "org_qprofiles"
  */
 public class RulesProfileDto {
 
+  /**
+   * Legacy db-generated ID. Usages should be replaced by {@link #kee}.
+   */
   private Integer id;
+
+  /**
+   * UUID. Can be a unique slug on legacy rows, for example "abap-sonar-way-38370".
+   */
   private String kee;
+
+  /**
+   * Name displayed to users, for example "Sonar way". Not null.
+   */
   private String name;
+
+  /**
+   * Language key, for example "java". Not null.
+   */
   private String language;
+
+  /**
+   * Date of last update of rule configuration (activation/deactivation/change of parameter).
+   * It does not include profile renaming.
+   * Not null.
+   */
   private String rulesUpdatedAt;
+
+  /**
+   * Whether profile is built-in or created by a user.
+   * A built-in profile is read-only. Its definition is provided by a language plugin.
+   */
   private boolean isBuiltIn;
 
   public String getKee() {
-- 
2.39.5