uilogger: improve language in comments

Change-Id: I8406bdf375cf83d504e45a5c8f27ce2ceb1f9c51
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/130190
Tested-by: Jenkins
Reviewed-by: Ilmari Lauhakangas <ilmari.lauhakangas@libreoffice.org>

8 files changed, 53 insertions, 69 deletions

diff --git a/uitest/ui_logger_dsl/General_commands.tx b/uitest/ui_logger_dsl/General_commands.tx
index 5f5c404402f5..2be59ce75f1a 100644
--- a/uitest/ui_logger_dsl/General_commands.tx
+++ b/uitest/ui_logger_dsl/General_commands.tx
@@ -1,9 +1,8 @@
 /*
-    This file for the log statements that is general for all application
-    we can use it as general commands then relate it to its application
-    as we have in the starter command
-    //====================================
-    also I make set zoom to be general as it will be better
+    This file is for the log statements that are general for all applications.
+    We can use them as general rules for commands and relate them to the
+    applications found in starter_commands.tx
+    Zoom is also general as it is better to treat it that way.
 */
 
 import type_options
@@ -21,9 +20,8 @@ Select_command:
     'Select ' '{"OBJECT":' name=STRING '}'
 ;
 
-//==================================================
-//This Part if you want to type text in any of these UI elements This will be handled with this Grammar
+// This part is for typing text in any of these UI elements
 
 General_type_command_on_UI_Object:
-  'Type on' UI_Obj=STRING  what_to_type=Type_options 'from' parent_id=ID  
-;
\ No newline at end of file
+  'Type on' UI_Obj=STRING  what_to_type=Type_options 'from' parent_id=ID
+;
diff --git a/uitest/ui_logger_dsl/Special_commands.tx b/uitest/ui_logger_dsl/Special_commands.tx
index 9d37029a5e95..fb3a6e235fa9 100644
--- a/uitest/ui_logger_dsl/Special_commands.tx
+++ b/uitest/ui_logger_dsl/Special_commands.tx
@@ -1,16 +1,16 @@
-import type_options
-
 /*
-    This file for the log statements that relates to each different applications
-    Each Grammar Command here is related to his own application
+    This file is for the log statements that relate to each application.
+    Each grammar rule here is related to a specific application.
 */
 
+import type_options
+
 SpecialCommand:
   writer_command | calc_command | impress_command | math_command | draw_command
 ;
 
 /*
-  This part for all the writer log statements:
+  This part is for all the Writer log statements:
 
     1)  Type
     2)  Select
@@ -20,8 +20,6 @@ SpecialCommand:
     6)  Cut Text
     7)  Paste Text
     8)  Insert Break Page
-
-  then we can add whatever we need in the future
 */
 writer_command:
     writer_Type_command | writer_Select_command | writer_GOTO_command |
@@ -32,7 +30,7 @@ writer_Type_command:
   'Type on writer' what_to_type=Type_options
 ;
 writer_Select_command:
-  'Select from Pos' from_pos=INT 'to Pos' to_pos=INT 
+  'Select from Pos' from_pos=INT 'to Pos' to_pos=INT
 ;
 writer_GOTO_command:
   'GOTO page number' page_num=INT
@@ -53,9 +51,8 @@ writer_Insert_BreakPage:
   'Insert Break Page'
 ;
 
-//=================================================================//
 /*
-  This part for all the calc log statements:
+  This part is for all the Calc log statements:
 
     1)  select sheet
     2)  Select cell or range
@@ -71,13 +68,11 @@ writer_Insert_BreakPage:
     12) Unmerge Cells
     13) Open Comment
     14) Close Comment
-
-  then we can add whatever we need in the future
 */
 calc_command:
   calc_Type_command | calc_switch_sheet | calc_Select_cell | calc_AutoFill_filter |
   calc_SelectMenu_filter | calc_Delete_Cells | calc_Remove_Content | calc_insert_cells |
-  calc_Cut_Cells | calc_Copy_Cells | calc_Paste_Cells | calc_UNMerge_Cells | 
+  calc_Cut_Cells | calc_Copy_Cells | calc_Paste_Cells | calc_UNMerge_Cells |
   calc_Merge_Cells | calc_Rename_Sheet | calc_Insert_sheet | calc_Open_Comment |
   calc_Close_Comment
 ;
@@ -144,17 +139,14 @@ select_options:
     one_cell | range_of_cells
 ;
 
-//=================================================================//
 /*
-  This part for all the impress log statements:
+  This part is for all the Impress log statements:
 
     1)  Type
     2)  Insert New Slide
     3)  Delete Slide
     4)  Duplicate Slide
     5)  Rename Slide
-
-  then we can add whatever we need in the future
 */
 impress_command:
     impress_Type_command | impress_Insert_Slide | impress_Delete_Page |
@@ -175,14 +167,11 @@ impress_Duplicate_Slide:
 impress_Rename_Slide:
     'Rename The Selected Slide from ' old_name=STRING 'to' new_name=STRING
 ;
-//=================================================================//
 /*
-  This part for all the math log statements:
+  This part is for all the Math log statements:
 
     1)  element selector
     2)  Type
-
-  then we can add whatever we need in the future
 */
 math_command:
     math_element_selector | math_Type_command
@@ -194,16 +183,13 @@ math_Type_command:
     'Type on math ' what_to_type=Type_options
 ;
 
-//=================================================================//
 /*
-  This part for all the draw log statements:
+  This part is for all the Draw log statements:
 
     1) Type
     2) Insert New Page
     3) Delete Page
     4) Rename Page
-
-  then we can add whatever we need in the future
 */
 draw_command:
     draw_Type_command | draw_Insert_Page | draw_Delete_Page |
@@ -222,17 +208,14 @@ draw_Rename_Page:
     'Rename The Selected Page from ' old_name=STRING 'to' new_name=STRING
 ;
 
-//=================================================================//
 /*
-  This part for all the Writer Comment statements:
+  This part is for all the Writer Comment log statements:
 
     1) Leave
     2) Hide
     3) Show
     4) Delete
     5) Set Resolved
-
-  then we can add whatever we need in the future
 */
 writer_Comment_command:
     writer_Comment_leave | writer_Comment_show | writer_Comment_hide |
@@ -252,4 +235,4 @@ writer_Comment_delete:
 ;
 writer_Comment_setresolved:
   'Resolve'  comment_id=STRING
-;
\ No newline at end of file
+;
diff --git a/uitest/ui_logger_dsl/UI_Object_commands.tx b/uitest/ui_logger_dsl/UI_Object_commands.tx
index f3d5d42903e5..4711ad6ac496 100644
--- a/uitest/ui_logger_dsl/UI_Object_commands.tx
+++ b/uitest/ui_logger_dsl/UI_Object_commands.tx
@@ -1,7 +1,5 @@
-import type_options
-
 /*
-    this file is for The Grammar of:
+    This file is for the grammar of:
         1)  ButtonUIObject : ( Click event )
         2)  EditUIObject	: ( Type event - Clear event - Select Text event )
         3)  CheckBoxUIObject	: ( Toggle the value  )
@@ -15,6 +13,8 @@ import type_options
         10)  MenuBtnUIObject ( Select - Open - Close )
 */
 
+import type_options
+
 UIObjectCommand:
   ButtonUIObject | CheckBoxUIObject | EditUIObject |
   RadioButtonUIObject | ListBoxUIObject | ComboBoxUIObject |
@@ -43,7 +43,7 @@ EditUIObject:
    action=action_on_UIObject ('from' parent_id=ID)?
 ;
 SpinFieldUIObject:
-   change=increase_or_ecrease Spin_id=STRING ('from' parent_id=ID)?
+   change=increase_or_decrease Spin_id=STRING ('from' parent_id=ID)?
 ;
 ListBoxUIObject:
    'Select element with position ' POS=INT 'in' list_id=STRING ('from' parent_id=ID)?
@@ -68,7 +68,7 @@ MenuBtnUIObjectSelect:
     'Select item no' + item_num=INT + 'From List of' + MenuBtn_ID=ID
 ;
 //=============================================================
-//helper grammar for EditUIObject
+// Helper grammar for EditUIObject
 action_on_UIObject:
     Type_action | SELECT | Clear
 ;
@@ -84,7 +84,7 @@ Clear:
 ;
 
 //=============================================================
-//helper functions for SpinUIObject
-increase_or_ecrease:
+// Helper functions for SpinUIObject
+increase_or_decrease:
   'Increase' | 'Decrease'
 ;
diff --git a/uitest/ui_logger_dsl/dialog_commands.tx b/uitest/ui_logger_dsl/dialog_commands.tx
index b1837f7efedb..637b54f0c976 100644
--- a/uitest/ui_logger_dsl/dialog_commands.tx
+++ b/uitest/ui_logger_dsl/dialog_commands.tx
@@ -1,7 +1,7 @@
 /*
-  this file for the Dialog commands
-  It handle all types of Dialog the Modeless and the Modal
-  Also It handle the Close Dialog Commands
+  This file is for the Dialog commands.
+  It handles all types of Dialog: the Modeless and the Modal.
+  It also handles the Close Dialog commands.
 */
 DialogCommand:
   OpenDialog | CloseDialog
@@ -18,7 +18,7 @@ OpenModelessDialog :
 ;
 
 CloseDialog:
-  //the additional_note=STRING? if you need to add name in the future
-  //Also it's used to make instance of the command of type CloseDialog
+  // If there is a need to match a dialog name in the future, additional_note=STRING? can be used.
+  // It is also used to make an instance of the command of type CloseDialog.
   'Close Dialog' additional_note=STRING?
 ;
diff --git a/uitest/ui_logger_dsl/dsl_core.py b/uitest/ui_logger_dsl/dsl_core.py
index 0629a2597da4..77c75eae9bf3 100644
--- a/uitest/ui_logger_dsl/dsl_core.py
+++ b/uitest/ui_logger_dsl/dsl_core.py
@@ -1,7 +1,13 @@
 #!/usr/bin/env python3
+# -*- tab-width: 4; indent-tabs-mode: nil; py-indent-offset: 4 -*-
+#
 # This file is part of the LibreOffice UI_logger project.
 #
-# This file contain the implementation of the Compiler
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# This file contains the implementation of the Compiler
 # for the new logger grammar
 #
 # ul stands for Ui_Logger
@@ -956,7 +962,7 @@ class ul_Compiler:
     def handle_math_element_selector(self, math_element_selector):
 
         if( self.math_element_selector_initializer == False ):
-            # This part to initialize the element selector in math application
+            # This part is for initializing the element selector in the Math application
             self.math_element_selector_initializer = True
             line = (
                 tab * 4
@@ -967,7 +973,7 @@ class ul_Compiler:
             )
             self.variables.append(line)
 
-        # this put a prefix of char 'x' to avoid variable with name equal to number only
+        # This inserts a prefix of 'x' to avoid creating variables with only numeric characters
         element_name="x"+str(math_element_selector.element_no)
 
         self.init_Object(element_name,str(math_element_selector.element_no),"element_selector")
diff --git a/uitest/ui_logger_dsl/starter_commands.tx b/uitest/ui_logger_dsl/starter_commands.tx
index 93fb0c2e0ab7..b581cf7a345c 100644
--- a/uitest/ui_logger_dsl/starter_commands.tx
+++ b/uitest/ui_logger_dsl/starter_commands.tx
@@ -1,13 +1,10 @@
-//this file for the starters commands when you open any LO application
-//It's translate automatic that the button you push to open the app is a starter button
+// This file is for the starter commands when you open any office application.
+// Button clicks for opening an application are automatically translated as coming from a starter button.
 
 StarterCommand:
   'Start' program_name=Program
 ;
 
-
 Program:
   "writer"|"calc"|"impress"|"draw"|"math"|"database"
 ;
-
-
diff --git a/uitest/ui_logger_dsl/ui_logger_dsl_grammar.tx b/uitest/ui_logger_dsl/ui_logger_dsl_grammar.tx
index 123c9b6f3398..717fb7172fea 100644
--- a/uitest/ui_logger_dsl/ui_logger_dsl_grammar.tx
+++ b/uitest/ui_logger_dsl/ui_logger_dsl_grammar.tx
@@ -1,8 +1,8 @@
-//this file is to define the new dsl grammar
 /*
-  This file just Import all Grammar Statements from all other files to this file
-  The Compiler just work with this file to Compile it
-  Each file of these imported file has a Comments related to it's content
+  This file is for defining the DSL grammar.
+  This file imports all grammar rules from all the other files.
+  The compiler works with this file.
+  Each imported file has comments related to its content.
 */
 
 import dialog_commands
@@ -13,7 +13,7 @@ import Special_commands
 import General_commands
 
 UILogger:
-    commands*=Command   
+    commands*=Command
 ;
 
 Command:
@@ -21,8 +21,8 @@ Command:
   SpecialCommand | GeneralCommand | Comment
 ;
 /*
-  The Comment Command is just for give the ability to write a Comment 
-  if you want to write a test Case in the new dsl language
+  The Comment rule is for having an ability to write a comment,
+  if you want to write a test case in the DSL
 */
 Comment:
   /\/\/.*$/
diff --git a/uitest/ui_logger_dsl/uno_commands.tx b/uitest/ui_logger_dsl/uno_commands.tx
index 15df9ef86f7f..597c855cb840 100644
--- a/uitest/ui_logger_dsl/uno_commands.tx
+++ b/uitest/ui_logger_dsl/uno_commands.tx
@@ -1,6 +1,6 @@
 /*
-    This file is for the grammar of the UNO Command Statements
-    It's Automatically have 2 modes one with parameters and one without
+    This file is for the grammar of the UNO commands.
+    It has two modes: one with parameters and one without.
 */
 
 UNOCommand:
@@ -17,4 +17,4 @@ data:
 
 value_type:
     INT|ID
-;
\ No newline at end of file
+;