From 01488e46ea35917fbfafe51e31943d3685619ef2 Mon Sep 17 00:00:00 2001
From: Dennis Ushakov <dennis.ushakov@gmail.com>
Date: Fri, 22 Jul 2016 11:53:04 +0300
Subject: [PATCH] more docs for IDEA-158425

---
 .../build/MacDistributionCustomizer.groovy    | 54 ++++++++++++++-----
 1 file changed, 40 insertions(+), 14 deletions(-)

diff --git a/build/groovy/org/jetbrains/intellij/build/MacDistributionCustomizer.groovy b/build/groovy/org/jetbrains/intellij/build/MacDistributionCustomizer.groovy
index b27ab792aa70..ebcaf33435f1 100644
--- a/build/groovy/org/jetbrains/intellij/build/MacDistributionCustomizer.groovy
+++ b/build/groovy/org/jetbrains/intellij/build/MacDistributionCustomizer.groovy
@@ -29,32 +29,38 @@ abstract class MacDistributionCustomizer {
    * The minimum version of Mac OS where the product is allowed to be installed
    */
   String minOSXVersion = "10.8"
+
   /**
    * Help bundle identifier for bundle in <a href="https://developer.apple.com/library/mac/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html">Apple Help Bundle</a> format
    * If there's no help bundled, leave empty
    */
   String helpId = ""
+
   /**
-   * String with declarations of additional file types that should be automatically opened by the application
+   * String with declarations of additional file types that should be automatically opened by the application.
    * Example:
-   * <dict>
-   *   <key>CFBundleTypeExtensions</key>
-   *   <array>
-   *     <string>extension</string>
-   *   </array>
-   *   <key>CFBundleTypeIconFile</key>
-   *   <string>path_to_icons.icns</string>
-   *   <key>CFBundleTypeName</key>
-   *   <string>File type description</string>
-   *   <key>CFBundleTypeRole</key>
-   *   <string>Editor</string>
-   * </dict>
+   * <pre>
+   * &lt;dict&gt;
+   *   &lt;key&gt;CFBundleTypeExtensions&lt;/key&gt;
+   *   &lt;array&gt;
+   *     &lt;string&gt;extension&lt;/string&gt;
+   *   &lt;/array&gt;
+   *   &lt;key&gt;CFBundleTypeIconFile&lt;/key&gt;
+   *   &lt;string&gt;path_to_icons.icns&lt;/string&gt;
+   *   &lt;key&gt;CFBundleTypeName&lt;/key&gt;
+   *   &lt;string&gt;File type description&lt;/string&gt;
+   *   &lt;key&gt;CFBundleTypeRole&lt;/key&gt;
+   *   &lt;string&gt;Editor&lt;/string&gt;
+   * &lt;/dict&gt;
+   * </pre>
    */
   String additionalDocTypes = ""
+
   /**
-   * Specify <scheme> here if you want product to be able to open urls like <scheme>://open?file=/some/file/path&line=0
+   * Specify &lt;scheme&gt; here if you want product to be able to open urls like <scheme>://open?file=/some/file/path&line=0
    */
   List<String> urlSchemes = []
+
   /**
    * CPU architectures app can be launched on, currently only x86_64 is supported
    */
@@ -76,6 +82,10 @@ abstract class MacDistributionCustomizer {
    */
   List<String> extraExecutables = []
 
+  /**
+   * An unique identifier string that specifies the app type of the bundle. The string should be in reverse DNS format using only the Roman alphabet in upper and lower case (A–Z, a–z), the dot (“.”), and the hyphen (“-”)
+   * See <a href="https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-102070">CFBundleIdentifier</a> for details
+   */
   String bundleIdentifier
 
   /**
@@ -88,10 +98,26 @@ abstract class MacDistributionCustomizer {
    */
   String dmgImagePathForEAP = null
 
+  /**
+   * Application bundle name: &lt;name&gt;.app. Current convention is to have ProductName.app for release and ProductName Version EAP.app.
+   * @param applicationInfo application info that can be used to check for EAP and building version
+   * @param buildNumber current build number
+   * @return application bundle directory name
+   */
   abstract String rootDirectoryName(ApplicationInfoProperties applicationInfo, String buildNumber)
 
+  /**
+   * Custom properties to be added to the properties file. They will be used for launched product, e.g. you can add additional logging in EAP builds
+   * @param applicationInfo application info that can be used to check for EAP and building version
+   * @return map propertyName-&gt;propertyValue
+   */
   Map<String, String> customIdeaProperties(ApplicationInfoProperties applicationInfo) { [:] }
 
+  /**
+   * Additional files to be copied to the distribution, e.g. help bundle or debugger binaries
+   * @param context build context that contains information about build directories, product properties and application info
+   * @param targetDirectory application bundle directory
+   */
   void copyAdditionalFiles(BuildContext context, String targetDirectory) {
   }
 }