Avatar2SysMLNames commented and cleaned

src/main/java/avatartranslator/tosysmlv2/Avatar2SysMLNames.java

@@ -46,13 +46,38 @@ package avatartranslator.tosysmlv2;
 import java.io.StringReader;
 import java.util.List;
 
+/**
+ * Class Avatar2SysMLNames
+ * Creation: 20/06/2024
+ *
+ * Generation of SysML idents from Avatar names.
+ *
+ * <p> This ensures that the identifiers used in the Avatar Model don't clash
+ * with the SysML keywords or some fieldName in the used SysML libraries.
+ * The parsing of AvatarFromSysML recovers the original Avatar names from these identifiers.
+ * "name" parameters for these name generators are intended to be the original Avatar names.
+ * Except for attributes, all the parameter names are short names (Avatar names without ".").
+ * </p>
+ * <p> Some name generators require an integer as last parameter. This parameter is used to be
+ * able to produce different identifiers for the same values of the other parameters</p>
+ *
+ * @author Sophie Coudert
+ * @version 0.1 20/06/2024
+ */
 public class Avatar2SysMLNames {
+    /** type of synchroneous communications */
     public final static int SYNC = 0;
+    /** type of blocking-fifo communications */
     public final static int BFIFO = 1;
+    /** type of non-blocking-fifo communications */
     public final static int NBFIFO = 2;
 
+
     public static String dataTypeSysMLname(String name){ return "'@dt:" + name.trim() + "'"; }
+
     public static String blockSysMLname(String name){ return "'@blk:" + name.trim() + "'"; }
+
+    /** attribute names may be chained using "." as separator */
     public static String attributeSysMLname(String _name){
         if (_name == null) return null;
         String name = _name.trim();
@@ -64,6 +89,8 @@ public class Avatar2SysMLNames {
             result.append(".'" + list[i] + "'");
         return result.toString();
     }
+
+    /** specific... as SysML requires a "::" as first separator (instead of ".") for variable assignment */
     public static String leftHandSysMLname(String name){
         String aname = attributeSysMLname(name);
         int found = aname.indexOf("'.'");
@@ -72,45 +99,100 @@ public class Avatar2SysMLNames {
                 aname.substring(0,found) + "'::'" + aname.substring(found+3)
                 );
     }
+    /** Note: method name are similar to attribute name (do not change, code rely on this) */
     public static String methodSysMLname(String name){ return "'$" + name.trim() + "'"; }
+
     public static String fieldSysMLname(String name){ return "'" + name.trim() + "'"; }
 
+    /** Relation names contain information about the kind of communication.
+     *
+     * @param b1 bloc name
+     * @param b2 bloc name
+     * @param type among SYNC, FIFO and NBFIFO
+     */
     public static String relationSysMLname(String b1, String b2, int type, int n){
         if (type == NBFIFO) return "'@NBF" + n + ":" + b1.trim() + "-" + b2.trim() + "'";
         if (type == BFIFO) return "'@BF" + n + ":" + b1.trim() + "-" + b2.trim() + "'";
         if (type == SYNC) return "'@SYN" + n + ":" + b1.trim() + "-" + b2.trim() + "'";
         return "";
     }
-    public static String channelName(String b1, String b2, String s1, String s2, boolean in2out){
-        if(in2out) return b1.trim() + "." + s1.trim() + ">" + b2.trim() + "." + s2.trim();
+
+    /** channelNames are informative substrings of channelSysMLNames.
+     *
+     * a channel connects two signals s1 and s2 belonging respectively to blocs b1 and b2
+     *
+     * @param out2in must be true if s1 is an output signal
+     */
+    public static String channelName(String b1, String b2, String s1, String s2, boolean out2in){
+        if(out2in) return b1.trim() + "." + s1.trim() + ">" + b2.trim() + "." + s2.trim();
         else return b1.trim() + "." + s1.trim() + "<" + b2.trim() + "." + s2.trim();
     }
-    public static String signalSysMLname(String s){ return "'@sig:" + s + "'"; }
+
+    public static String signalSysMLname(String _name){ return "'@sig:" + _name + "'"; }
+
+    /** Channel SysML names contain information about the kind of communication.
+     *
+     * @param type among SYNC, FIFO and NBFIFO
+     */
     public static String channelSysMLname(String _signalname, int type){
         if (type == NBFIFO) return "'@nbf:" + _signalname.trim() + "'";
         if (type == BFIFO) return "'@bf:" + _signalname.trim() + "'";
         if (type == SYNC) return "'@syn:" + _signalname.trim() + "'";
         return "";
     }
+
+    /** messages denote structures that are signal profiles */
     public static String messageSysMLname(String _blockname, String _signalsname){
         return "'@MSG:" + _blockname.trim() + "." + _signalsname.trim() + "'";
     }
+
     public static String startStateSysMLname(){ return "'@st:start'"; }
+
     public static String stopStateSysMLname(){ return "'@st:stop'"; }
+
+    /** associated to AvatarStates */
     public static String standardStateSysMLname(String name){ return "'@st:standard." + name.trim() + "'"; }
+
+    /** associated to AvatarRandoms */
     public static String randomStateSysMLname(int number){ return "'@st:random." + number + "'"; }
+
+    /** associated to QueriesOnSignal */
     public static String countStateSysMLname(String sigName, int number){ return "'@st:count." + sigName.trim() + "." + number + "'"; }
+
+    /** associated to sending AvatarActionOnSignal */
     public static String sendStateSysMLname(String sigName, int number){ return "'@st:send." + sigName.trim() + "." + number + "'"; }
+
+    /** associated to receiving AvatarActionOnSignal */
     public static String receiveStateSysMLname(String sigName, int number){ return "'@st:receive." + sigName.trim() + "." + number + "'"; }
+
+    /** (technical) added states before some sending AvatarActionOnSignal */
     public static String presendStateSysMLname(String sigName, int number){ return "'@st:presend." + sigName.trim() + "." + number + "'"; }
+
+    /** (technical) added states before some receiving AvatarActionOnSignal */
     public static String prereceiveStateSysMLname(String sigName, int number){ return "'@st:prereceive." + sigName.trim() + "." + number + "'"; }
+
+    /** associated to AvatarSetTimer */
     public static String setTimerStateSysMLname(String timerName, int number){ return "'@st:set." + timerName.trim() + "." + number + "'"; }
+
+    /** associated to AvatarResetTimer */
     public static String resetTimerStateSysMLname(String timerName, int number){ return "'@st:reset." + timerName.trim() + "." + number + "'"; }
+
+    /** associated to AvatarExpireTimer */
     public static String expireTimerStateSysMLname(String timerName, int number){ return "'@st:expire." + timerName.trim() + "." + number + "'"; }
+
+    /** (technical) added states before some AvatarSetTimer */
     public static String presetTimerStateSysMLname(String timerName, int number){ return "'@st:preset." + timerName.trim() + "." + number + "'"; }
+
+    /** (technical) added states before some AvatarResetTimer */
     public static String preresetTimerStateSysMLname(String timerName, int number){ return "'@st:prereset." + timerName.trim() + "." + number + "'"; }
+
+    /** (technical) added states before some AvatarExpireTimer */
     public static String preexpireTimerStateSysMLname(String timerName, int number){ return "'@st:preexpire." + timerName.trim() + "." + number + "'"; }
+
+    /** associated to Avatar timers (represented by blocks) */
     public static String timerBlockSysMLname(String timerName){ return "'@tmr:" + timerName.trim() + "'"; }
+
+    /** convert an Avatar int/bool expression into a SysML expression */
     public static String expr2SysML(String _expr) {
         Avatar2SysMLParser parser = new Avatar2SysMLParser(new Avatar2SysMLLexer(new StringReader (_expr)));
         try { return (String)parser.parse().value; }