From f5dd6887467f4ba5090c12dbc6559ae02dfca389 Mon Sep 17 00:00:00 2001
From: Pavel Talanov <Pavel.Talanov@jetbrains.com>
Date: Sun, 5 Feb 2012 16:33:47 +0400
Subject: [PATCH] fix cosmetic TODOs add short class comments where meaningful

---
 .../src/org/jetbrains/k2js/config/Config.java   |  2 ++
 .../jetbrains/k2js/facade/K2JSTranslator.java   | 17 ++++-------------
 .../k2js/facade/K2JSTranslatorApplet.java       |  2 ++
 .../jetbrains/k2js/translate/context/Namer.java |  9 ++++++++-
 .../k2js/translate/context/NamingScope.java     | 12 +++++++-----
 .../k2js/translate/context/StandardClasses.java |  3 +++
 .../k2js/translate/context/StaticContext.java   |  5 +++++
 .../translate/context/TranslationContext.java   |  2 ++
 .../declaration/ClassDeclarationTranslator.java |  2 ++
 .../translate/declaration/ClassTranslator.java  |  2 ++
 .../declaration/NamespaceTranslator.java        |  4 ++--
 .../declaration/PropertyTranslator.java         |  2 ++
 .../k2js/translate/intrinsic/Intrinsic.java     |  2 ++
 .../k2js/translate/intrinsic/Intrinsics.java    |  2 ++
 .../translate/reference/AccessTranslator.java   |  2 ++
 .../KotlinPropertyAccessTranslator.java         |  2 ++
 .../NativePropertyAccessTranslator.java         |  2 ++
 .../k2js/translate/utils/DescriptorUtils.java   |  4 ++--
 .../k2js/translate/utils/PsiUtils.java          | 11 +++++++++++
 .../org/jetbrains/k2js/utils/ErrorSender.java   |  2 ++
 .../jetbrains/k2js/utils/GenerationUtils.java   |  2 ++
 21 files changed, 68 insertions(+), 23 deletions(-)

diff --git a/translator/src/org/jetbrains/k2js/config/Config.java b/translator/src/org/jetbrains/k2js/config/Config.java
index bbb983b933e..b36f22126c8 100644
--- a/translator/src/org/jetbrains/k2js/config/Config.java
+++ b/translator/src/org/jetbrains/k2js/config/Config.java
@@ -15,6 +15,8 @@ import java.util.List;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Base class reprenting a configuration of translator.
  */
 public abstract class Config {
 
diff --git a/translator/src/org/jetbrains/k2js/facade/K2JSTranslator.java b/translator/src/org/jetbrains/k2js/facade/K2JSTranslator.java
index 5353f614aff..d5c57a6b038 100644
--- a/translator/src/org/jetbrains/k2js/facade/K2JSTranslator.java
+++ b/translator/src/org/jetbrains/k2js/facade/K2JSTranslator.java
@@ -5,7 +5,6 @@ import com.intellij.openapi.project.Project;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.jet.lang.descriptors.NamespaceDescriptor;
 import org.jetbrains.jet.lang.psi.JetFile;
-import org.jetbrains.jet.lang.psi.JetNamespaceHeader;
 import org.jetbrains.jet.lang.resolve.BindingContext;
 import org.jetbrains.k2js.analyze.Analyzer;
 import org.jetbrains.k2js.config.Config;
@@ -25,12 +24,15 @@ import java.util.Arrays;
 import java.util.List;
 import java.util.StringTokenizer;
 
+import static org.jetbrains.k2js.translate.utils.PsiUtils.getNamespaceName;
 import static org.jetbrains.k2js.utils.JetFileUtils.createPsiFileList;
 
 //TODO: clean up the code
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         An entry point of translator.
  */
 public final class K2JSTranslator {
 
@@ -104,7 +106,7 @@ public final class K2JSTranslator {
 
     @NotNull
     public String generateCallToMain(@NotNull JetFile file, @NotNull String argumentString) {
-        String namespaceName = getRootNamespaceName(file);
+        String namespaceName = getNamespaceName(file);
         List<String> arguments = parseString(argumentString);
         return GenerationUtils.generateCallToMain(namespaceName, arguments);
     }
@@ -119,17 +121,6 @@ public final class K2JSTranslator {
         return result;
     }
 
-    @NotNull
-    private String getRootNamespaceName(@NotNull JetFile psiFile) {
-        JetNamespaceHeader namespaceHeader = psiFile.getNamespaceHeader();
-        String name = namespaceHeader.getName();
-        assert name != null : "NamespaceHeader must have a name";
-        //TODO: encapsulate anonymous logic somewhere
-        if (name.equals("")) {
-            return "Anonymous";
-        }
-        return name;
-    }
 
     @NotNull
     private Project getProject() {
diff --git a/translator/src/org/jetbrains/k2js/facade/K2JSTranslatorApplet.java b/translator/src/org/jetbrains/k2js/facade/K2JSTranslatorApplet.java
index 9595a319fa7..dc1066d63d9 100644
--- a/translator/src/org/jetbrains/k2js/facade/K2JSTranslatorApplet.java
+++ b/translator/src/org/jetbrains/k2js/facade/K2JSTranslatorApplet.java
@@ -11,6 +11,8 @@ import java.io.StringWriter;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Represents an applet API for WebDemo module.
  */
 public final class K2JSTranslatorApplet extends Applet {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/context/Namer.java b/translator/src/org/jetbrains/k2js/translate/context/Namer.java
index cf93301d665..3f12455cb2b 100644
--- a/translator/src/org/jetbrains/k2js/translate/context/Namer.java
+++ b/translator/src/org/jetbrains/k2js/translate/context/Namer.java
@@ -8,8 +8,9 @@ import org.jetbrains.annotations.NotNull;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Encapuslates different types of constants and naming conventions.
  */
-
 public final class Namer {
 
     private static final String INITIALIZE_METHOD_NAME = "initialize";
@@ -22,6 +23,12 @@ public final class Namer {
     private static final String BACKING_FIELD_PREFIX = "$";
     private static final String SUPER_METHOD_NAME = "super_init";
     private static final String KOTLIN_OBJECT_NAME = "Kotlin";
+    private static final String ANONYMOUS_NAMESPACE = "Anonymous";
+
+    @NotNull
+    public static String getAnonymousNamespaceName() {
+        return ANONYMOUS_NAMESPACE;
+    }
 
     @NotNull
     public static JsNameRef initializeMethodReference() {
diff --git a/translator/src/org/jetbrains/k2js/translate/context/NamingScope.java b/translator/src/org/jetbrains/k2js/translate/context/NamingScope.java
index 93574d36e78..45d61ea7f03 100644
--- a/translator/src/org/jetbrains/k2js/translate/context/NamingScope.java
+++ b/translator/src/org/jetbrains/k2js/translate/context/NamingScope.java
@@ -6,6 +6,8 @@ import org.jetbrains.annotations.NotNull;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Basically a wrapper around JsScope.
  */
 public final class NamingScope {
 
@@ -39,6 +41,11 @@ public final class NamingScope {
         return declaredName;
     }
 
+    @NotNull
+        /*package*/ JsName declareObfuscatableName(@NotNull String name) {
+        return scope.declareName(mayBeObfuscateName(name, true));
+    }
+
     //TODO: temporary solution
     @NotNull
     private String mayBeObfuscateName(@NotNull String name, boolean shouldObfuscate) {
@@ -64,11 +71,6 @@ public final class NamingScope {
         return result;
     }
 
-    @NotNull
-        /*package*/ JsName declareObfuscatableName(@NotNull String name) {
-        return scope.declareName(mayBeObfuscateName(name, true));
-    }
-
     public JsName declareTemporary() {
         return scope.declareTemporary();
     }
diff --git a/translator/src/org/jetbrains/k2js/translate/context/StandardClasses.java b/translator/src/org/jetbrains/k2js/translate/context/StandardClasses.java
index 77b613b3abe..be85544777f 100644
--- a/translator/src/org/jetbrains/k2js/translate/context/StandardClasses.java
+++ b/translator/src/org/jetbrains/k2js/translate/context/StandardClasses.java
@@ -13,6 +13,9 @@ import static org.jetbrains.jet.lang.resolve.DescriptorUtils.getFQName;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Provides a mechanism to bind some of the kotlin/java declations with library implementations.
+ *         Makes sense only for those declaration that cannot be annotated. (Use library annotation in this case)
  */
 public final class StandardClasses {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/context/StaticContext.java b/translator/src/org/jetbrains/k2js/translate/context/StaticContext.java
index e3a3262fafc..43bc58a8a8d 100644
--- a/translator/src/org/jetbrains/k2js/translate/context/StaticContext.java
+++ b/translator/src/org/jetbrains/k2js/translate/context/StaticContext.java
@@ -18,6 +18,11 @@ import org.jetbrains.k2js.translate.utils.AnnotationsUtils;
 import static org.jetbrains.k2js.translate.utils.AnnotationsUtils.*;
 import static org.jetbrains.k2js.translate.utils.DescriptorUtils.*;
 
+/**
+ * @author Pavel Talanov
+ *         <p/>
+ *         Aggregates all the static parts of the context.
+ */
 public class StaticContext {
 
     public static StaticContext generateStaticContext(@NotNull JetStandardLibrary library,
diff --git a/translator/src/org/jetbrains/k2js/translate/context/TranslationContext.java b/translator/src/org/jetbrains/k2js/translate/context/TranslationContext.java
index 432a09d9483..77d1bf4b06a 100644
--- a/translator/src/org/jetbrains/k2js/translate/context/TranslationContext.java
+++ b/translator/src/org/jetbrains/k2js/translate/context/TranslationContext.java
@@ -12,6 +12,8 @@ import static org.jetbrains.k2js.translate.utils.BindingUtils.getDescriptorForEl
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         All the info about the state of the translation process.
  */
 public final class TranslationContext {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/declaration/ClassDeclarationTranslator.java b/translator/src/org/jetbrains/k2js/translate/declaration/ClassDeclarationTranslator.java
index ee10296ae7d..ef3ed421540 100644
--- a/translator/src/org/jetbrains/k2js/translate/declaration/ClassDeclarationTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/declaration/ClassDeclarationTranslator.java
@@ -24,6 +24,8 @@ import static org.jetbrains.k2js.translate.utils.BindingUtils.getDeclarationsFor
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Generates a big block where are all the classes(objects representing them) are created.
  */
 //TODO: declaration translator receives NamespaceDescriptor while actually should receive all declarations in namespace
 public final class ClassDeclarationTranslator extends AbstractTranslator {
diff --git a/translator/src/org/jetbrains/k2js/translate/declaration/ClassTranslator.java b/translator/src/org/jetbrains/k2js/translate/declaration/ClassTranslator.java
index 654dc544b47..65fad9a0dd4 100644
--- a/translator/src/org/jetbrains/k2js/translate/declaration/ClassTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/declaration/ClassTranslator.java
@@ -22,6 +22,8 @@ import static org.jetbrains.k2js.translate.utils.PsiUtils.getPrimaryConstructorP
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Generates a definition of a single class.
  */
 public final class ClassTranslator extends AbstractTranslator {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/declaration/NamespaceTranslator.java b/translator/src/org/jetbrains/k2js/translate/declaration/NamespaceTranslator.java
index dda8b8db198..5390c8cdacc 100644
--- a/translator/src/org/jetbrains/k2js/translate/declaration/NamespaceTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/declaration/NamespaceTranslator.java
@@ -14,9 +14,9 @@ import java.util.List;
 
 /**
  * @author Pavel.Talanov
+ *         <p/>
+ *         Translates single namespace.
  */
-//TODO: rework translator to translateAsLocalNameReference everything in the namespace not only in one file
-// TEST IT
 public final class NamespaceTranslator extends AbstractTranslator {
 
     @NotNull
diff --git a/translator/src/org/jetbrains/k2js/translate/declaration/PropertyTranslator.java b/translator/src/org/jetbrains/k2js/translate/declaration/PropertyTranslator.java
index 5dfc62106be..74d3978e50b 100644
--- a/translator/src/org/jetbrains/k2js/translate/declaration/PropertyTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/declaration/PropertyTranslator.java
@@ -22,6 +22,8 @@ import static org.jetbrains.k2js.translate.utils.TranslationUtils.*;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Translates single property /w accessors.
  */
 public final class PropertyTranslator extends AbstractTranslator {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsic.java b/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsic.java
index 87c65543580..5fc9ca07c2a 100644
--- a/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsic.java
+++ b/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsic.java
@@ -9,6 +9,8 @@ import java.util.List;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Base class for all intrinsics.
  */
 public interface Intrinsic {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsics.java b/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsics.java
index e5c7b3c347a..dd93442db80 100644
--- a/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsics.java
+++ b/translator/src/org/jetbrains/k2js/translate/intrinsic/Intrinsics.java
@@ -28,6 +28,8 @@ import static org.jetbrains.k2js.translate.utils.DescriptorUtils.getPropertyByNa
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Provides mechanism to substitute method calls /w native constucts directly.
  */
 public final class Intrinsics {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/reference/AccessTranslator.java b/translator/src/org/jetbrains/k2js/translate/reference/AccessTranslator.java
index d05e3413751..6e7e05d277f 100644
--- a/translator/src/org/jetbrains/k2js/translate/reference/AccessTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/reference/AccessTranslator.java
@@ -9,6 +9,8 @@ import org.jetbrains.k2js.translate.general.AbstractTranslator;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Abstract entity for language constructs that you can get/set. Also dispatches to the real implemntation.
  */
 public abstract class AccessTranslator extends AbstractTranslator {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/reference/KotlinPropertyAccessTranslator.java b/translator/src/org/jetbrains/k2js/translate/reference/KotlinPropertyAccessTranslator.java
index 0486f9150cb..126cd19d080 100644
--- a/translator/src/org/jetbrains/k2js/translate/reference/KotlinPropertyAccessTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/reference/KotlinPropertyAccessTranslator.java
@@ -15,6 +15,8 @@ import static org.jetbrains.k2js.translate.utils.TranslationUtils.backingFieldRe
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         For properies /w accessors.
  */
 public final class KotlinPropertyAccessTranslator extends PropertyAccessTranslator {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/reference/NativePropertyAccessTranslator.java b/translator/src/org/jetbrains/k2js/translate/reference/NativePropertyAccessTranslator.java
index ffdec57d561..c6c8a0817df 100644
--- a/translator/src/org/jetbrains/k2js/translate/reference/NativePropertyAccessTranslator.java
+++ b/translator/src/org/jetbrains/k2js/translate/reference/NativePropertyAccessTranslator.java
@@ -14,6 +14,8 @@ import static org.jetbrains.k2js.translate.utils.DescriptorUtils.getExpectedThis
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         For native apis that use .property notation for access.
  */
 public final class NativePropertyAccessTranslator extends PropertyAccessTranslator {
 
diff --git a/translator/src/org/jetbrains/k2js/translate/utils/DescriptorUtils.java b/translator/src/org/jetbrains/k2js/translate/utils/DescriptorUtils.java
index 2355bc738d0..49ae1de3727 100644
--- a/translator/src/org/jetbrains/k2js/translate/utils/DescriptorUtils.java
+++ b/translator/src/org/jetbrains/k2js/translate/utils/DescriptorUtils.java
@@ -6,6 +6,7 @@ import org.jetbrains.jet.lang.descriptors.*;
 import org.jetbrains.jet.lang.resolve.scopes.JetScope;
 import org.jetbrains.jet.lang.resolve.scopes.receivers.ReceiverDescriptor;
 import org.jetbrains.jet.lang.types.expressions.OperatorConventions;
+import org.jetbrains.k2js.translate.context.Namer;
 
 import java.util.ArrayList;
 import java.util.Collection;
@@ -125,12 +126,11 @@ public final class DescriptorUtils {
         return (functionDescriptor.getReceiverParameter().exists());
     }
 
-    //TODO: make "anonymous" a constant
     @NotNull
     public static String getNameForNamespace(@NotNull NamespaceDescriptor descriptor) {
         String name = descriptor.getName();
         if (name.equals("")) {
-            return "Anonymous";
+            return Namer.getAnonymousNamespaceName();
         }
         return name;
     }
diff --git a/translator/src/org/jetbrains/k2js/translate/utils/PsiUtils.java b/translator/src/org/jetbrains/k2js/translate/utils/PsiUtils.java
index c280f0aa400..4432cb51d46 100644
--- a/translator/src/org/jetbrains/k2js/translate/utils/PsiUtils.java
+++ b/translator/src/org/jetbrains/k2js/translate/utils/PsiUtils.java
@@ -7,6 +7,7 @@ import org.jetbrains.annotations.Nullable;
 import org.jetbrains.jet.lang.psi.*;
 import org.jetbrains.jet.lexer.JetToken;
 import org.jetbrains.jet.lexer.JetTokens;
+import org.jetbrains.k2js.translate.context.Namer;
 
 import java.util.Collections;
 import java.util.List;
@@ -116,6 +117,16 @@ public final class PsiUtils {
         assert parent instanceof JetObjectDeclaration :
                 "ObjectDeclarationName should have a parent of type ObjectDeclaration.";
         return (JetObjectDeclaration) parent;
+    }
 
+    @NotNull
+    public static String getNamespaceName(@NotNull JetFile psiFile) {
+        JetNamespaceHeader namespaceHeader = psiFile.getNamespaceHeader();
+        String name = namespaceHeader.getName();
+        assert name != null : "NamespaceHeader must have a name";
+        if (name.equals("")) {
+            return Namer.getAnonymousNamespaceName();
+        }
+        return name;
     }
 }
diff --git a/translator/src/org/jetbrains/k2js/utils/ErrorSender.java b/translator/src/org/jetbrains/k2js/utils/ErrorSender.java
index ba131811796..aa1b2a63662 100644
--- a/translator/src/org/jetbrains/k2js/utils/ErrorSender.java
+++ b/translator/src/org/jetbrains/k2js/utils/ErrorSender.java
@@ -11,6 +11,8 @@ import java.net.URL;
 
 /**
  * @author Pavel Talanov
+ *         <p/>
+ *         Some util class for WebDemo module.
  */
 public final class ErrorSender {
 
diff --git a/translator/src/org/jetbrains/k2js/utils/GenerationUtils.java b/translator/src/org/jetbrains/k2js/utils/GenerationUtils.java
index 2e3bcc41ab9..3aacc85a56a 100644
--- a/translator/src/org/jetbrains/k2js/utils/GenerationUtils.java
+++ b/translator/src/org/jetbrains/k2js/utils/GenerationUtils.java
@@ -4,6 +4,8 @@ import org.jetbrains.annotations.NotNull;
 
 import java.util.List;
 
+//TODO: very thin class
+
 /**
  * @author Pavel Talanov
  */