Issue#545 Extend generated java doco to include private methods (z390…

…development#553)

* Change javadoc invocation to generate doco for private methods as well

* Fix incorrect javadoc comments

* Modifying bash\bldjvdoc to remain in agreement with bat\BLDJVDOC.BAT

* Improving doco item for javadoc

bash/bldjavadoc

@@ -17,7 +17,7 @@ rm -rf ${DEST}/*
 
 # build the javadoc
 echo "Building javadoc from src/*.java into ${DEST} directory ..."
-javadoc -quiet -Xdoclint:none -d ${DEST} src/*.java
+javadoc -quiet -Xdoclint:none -d ${DEST} -private src/*.java
 ec=$?
 echo "The exit code of the javadoc command is $ec"
 if [ $ec -ne 0 ]; then echo "bldjavadoc Error encountered building javadoc"; fi

bat/BLDJVDOC.BAT

@@ -15,7 +15,7 @@ pushd %~dps0..
 rem generate javadoc
 if not exist ".\docenv\javadoc\" mkdir docenv\javadoc
 cd docenv\javadoc
-call javadoc.exe ..\..\src\*.java || goto error
+call javadoc.exe ..\..\src\*.java -private || goto error
 cd ..\..
 goto return
 

src/az390.java

@@ -424,6 +424,7 @@ public  class  az390 implements Runnable {
         * 2024-05-29 afk #500 List suboption for options optable/machine not implemented correctly
         * 2024-07-03 jjg #509 generate error in process_dcc_data if "DC  C''"
         * 2024-08-09 AFK #543 Correct OPTABLE(XA,LIST) output to match HLASM
+        * 2024-08-12 #545 Extend generated java doco to include private methods
 	*****************************************************
     * Global variables                        last rpi
     *****************************************************/
@@ -1744,10 +1745,7 @@ private void reset_lits(){
      * The report entries are sorted
      * The sorted entries are printed (three on a print line) preceded by a header line
      *
-     * @param (none)
-     * @return (none)
      */
-
 private void gen_list_mnemonics() // Routine added for RPI 1209A
    {int     index;
     String  entry;

src/ez390.java

@@ -175,6 +175,7 @@
     * 05/10/11 RPI 1149 move started msg to put_trace
     * 07/30/11 RPI 1175 use tz390.check_java_version()
     * 2023-01-22 RPI 1598 re-implement javadoc changes by Hugh Sweeney
+    * 2024-08-12 #545 Extend generated java doco to include private methods
     ********************************************************
     * Global variables                       (last RPI)
     *****************************************************/
@@ -294,7 +295,7 @@ public void process_ez390(String[] args,JTextArea log_text,JTextField command_te
     /**
      * execute IPL pgm and/or application pgm
      *
-     * @param zcvt_pgm_addr
+     * @param zcvt_pgm_addr - address of 8 byte field containing name of program to run
      */
 private void run_pgm(int zcvt_pgm_addr){
 	pz390.reg.putInt(pz390.r13,pz390.zcvt_save);
@@ -438,7 +439,7 @@ public void actionPerformed(ActionEvent evt) {
 	 *     cmd processes if running with timeout
 	 *  
 	 * 2.  If CMD running and 
-	 *     monitor_wait_total > timeout_interval
+	 *     monitor_wait_total > timeout_interval
 	 *     then abort cmd process with timeout
 	 *  
 	 * 3.  If current time beyond timeout

src/gz390.java

@@ -129,12 +129,13 @@ public  class  gz390
 	 * 06/22/09 RPI 1061 include PA_MDT in returned TGET fields with SBA's   
 	 * 10/24/09 RPI 1091 remove extra field advance for SFE                             
 	 * 01/01/10 RPI 1094 skip unprotected fields on tab, abort if timeout
-	 * 05/10/11 RPI 1151 correct set field attribute higlight & color
+	 * 05/10/11 RPI 1151 correct set field attribute higlight and color
 	 * 07/30/11 RPI 1175 use tz390.check_java_version()
 	 * 2019-09-20 dsh fix depreciated ALT_MASK to ALT_DOWN_MASK
 	 *                and CTRL_MASK to CTRL_DOWN_MASK
 	 * 2019-09-21 dsh remove getContentPane
 	 *                            replace getModifiers() with getModifiersEx()
+	 * 2024-08-12 #545 Extend generated java doco to include private methods
 	 ********************************************************
      * Global variables                   (last rpi)
      *****************************************************
@@ -2234,10 +2235,10 @@ public void componentShown(ComponentEvent e) {
    //dsh     	System.out.println("componentShown event from "
    //dsh     		       + e.getComponent().getClass().getName());
             }
-     /***********************************************
+     /* **********************************************
       * Private screen, graph, keybaord, mouse, sound 
       * functions
-      ***********************************************/
+      ********************************************** */
 private void tput_edit_buffer(byte[] buff, int lbuff){
 	/*
 	 * update screen from tput ebcdic buffer

src/tz390.java

@@ -330,6 +330,7 @@ public  class  tz390 {
     * 2024-05-30 AFK #500 List suboption for options optable/machine not implemented correctly
     * 2024-06-07 AFK #533 Correct OPTABLE(370,LIST) output to match HLASM
     * 2024-08-01 AFK #543 Correct OPTABLE(XA,LIST) output to match HLASM
+    * 2024-08-12 #545 Extend generated java doco to include private methods
 	********************************************************
     * Shared z390 tables                  (last RPI)
     *****************************************************/
@@ -8022,7 +8023,7 @@ private boolean isPrintableChar_ISO_8859_1(char c)
      * when using the US-ASCII Charset.
      *
      * @param    c  character to check
-     * @returns  {@code true} if printable, {@code false} if non-printable.
+     * @return  {@code true} if printable, {@code false} if non-printable.
      */
     private boolean isPrintableChar_US_ASCII(char c)
     {
@@ -8038,9 +8039,9 @@ private boolean isPrintableChar_US_ASCII(char c)
 
     /**
      * <ol>
-     * </li> copy test tables to live tables
-     * </li> initialize translate tables
-     * </li> initialize printable character table
+     * <li> copy test tables to live tables</li>
+     * <li> initialize translate tables</li>
+     * <li> initialize printable character table</li>
      * </ol>
      */
 private void init_charset_tables(){
@@ -8098,6 +8099,7 @@ private void init_charset_tables(){
 
     /**
      * report codepage parm error
+     * @param msg String message text
      */
 private void report_codepage_error(String msg){
 
@@ -8132,6 +8134,7 @@ private void list_ebcdic_ascii_unicode(){
 
 
     /**
+     * @param index for codepoint
      * @return text index,hex-ebcdic,hex-ascii,char,U+hex
      */
 private String map_text(int index){

src/vz390.java

@@ -75,6 +75,7 @@ public class vz390 {
      *            1. Correct three VCLR "control block" offset values to match VCLR DSECT.
      *            2. Add initialization code for all "control blocks". Invoked in open and close.
      *            3, Modify find_vclr() and fetch_vclr_fields() to correctly process "PATH NAMELIST".
+     * 2024-08-12 #545 Extend generated java doco to include private methods
 	 **************************************************************************
 	 *  Global variables                  (last RPI)
 	 **************************************************************************/
@@ -1188,7 +1189,7 @@ private boolean load_vcdt() {
      * find VCLR/VPTH entry in VCDT
      * <ol>
      * <li> Set cur_vclra_addr </li> 
-     * <li> Set cur_vptha_addr or 0 </li> 
+     * <li> Set cur_vptha_addr or 0
      *    <ol>
      *    <li> If vpth_flag_aixp, set acb_oflgs_aixp else 0 </li> 
      *    <li> If vpth_flag_aixu, set acb_oflgs_aixu else 0 </li> 
@@ -1350,6 +1351,7 @@ private void fetch_rpl_fields() {
 
     /**
      * check for consistency between VCDT and ACB options and if
+     * @return true
      */
     private boolean check_acb_macrf() {
 
@@ -1673,9 +1675,11 @@ private void rpl_get_esds_adr() {
 
     /**
      * <ol>
-     * set RPLLXRBA last rec XRBA
-     * <li> VES for ESDS/RRDS </li>
-     * <li> VX0 for KSDS/VRRDS </li>
+     * <li>set RPLLXRBA last rec XRBA
+     *     <ol>
+     *     <li> VES for ESDS/RRDS </li>
+     *     <li> VX0 for KSDS/VRRDS </li>
+     *     </ol></li>
      * </ol>
      * @param xrba - long
      */
@@ -1700,9 +1704,11 @@ private void set_rpl_cxrba(long xrba) {
 
     /**
      * <ol>
-     * set RPLLXRBA last rec XRBA
-     * <li> VES for ESDS/RRDS </li>
-     * <li> VX0 for KSDS/VRRDS </li>
+     * <li>set RPLLXRBA last rec XRBA
+     *     <ol>
+     *     <li> VES for ESDS/RRDS </li>
+     *     <li> VX0 for KSDS/VRRDS </li>
+     *     </ol></li>
      * </ol>
      */
     private void set_rpl_ksit() {
@@ -2301,11 +2307,11 @@ private boolean get_ksir_rec() {
      /**
       * <ol>
       * <li> if random access by key rec #, then cur_vx0_rba = rec# * 8 else cur_vx0_xrba = cur_rpl_cxrba. </li>
-      * <li> Set cur_ves_xrba as follows if cur_vx0_xrba > eod set cur_vx0_xrba = -1 (not found) and return false </li>
+      * <li> Set cur_ves_xrba as follows if cur_vx0_xrba &gt; eod set cur_vx0_xrba = -1 (not found) and return false </li>
       * <li> Set cur_ves_xrba as follows:
       *    <ol>
       *    <li> -1 if 0 return false (no rec found) </li>
-      *    <li> xrba and return true. </li> </li>
+      *    <li> xrba and return true. </li>
       *    </ol> </li>
       * </ol>
       * Note:
@@ -2607,7 +2613,7 @@ private boolean rewrite_ves_rec(int tiot_index, long xrba_index) {
      * add RRDS or KSDS record to VES and update index XRBA address which
      * may be in VX0 or in VES KSIR.
      * @param tiot_index - int
-     * @param index_rba - long
+     * @param index_xrba - long
      * @return boolean to indicate success (true) or failure (false)
      */
     private boolean add_ves_rec(int tiot_index, long index_xrba) {
@@ -3577,9 +3583,9 @@ private boolean rpl_key_high_values() {
     /**
      * get VSAM Cache Buffer (VCB) for file tiot_index, xrba, rec_len 
      * <ol>
-     * <li> If rec_len > max_vcb_lrec return false. </li>
-     * <li> search for allocated vcb If not found add new vcb up to  </li>
-     *      max_vcb else replace least recently used allocated vcb. 
+     * <li> If rec_len &gt; max_vcb_lrec return false. </li>
+     * <li> search for allocated vcb If not found add new vcb up to
+     *      max_vcb else replace least recently used allocated vcb.</li>
      * <li> Set vcb_index and return true. </li>
      * </ol>
      * @param tiot_index - int - index into tiot
@@ -3740,6 +3746,7 @@ private boolean read_ksit() {
 
     /**
      * read KSIR int cb and set cur_ksit xrba's
+     * @param xrba long input xrba value
      * @return boolean to indicate success (true) or failure (false)
      */
     private boolean read_ksir(long xrba) {

src/z390.java

@@ -94,7 +94,7 @@ public  class  z390
      * 10/04/05 RPI   6 - option ERR nn limit errors
      * 10/04/05 trap any command errors and issue 51
      * 10/09/05 RPI  16 - remove TEST and TRACE dependency bug
-     * 10/12/05 RPI  15 & 17 - fix CMD processing and status line
+     * 10/12/05 RPI  15 and 17 - fix CMD processing and status line
      * 10/18/05 RPI  29 - use Z390E and Z390I prefixes 
      * 10/27/05 RPI  55 - change /SC to execute Z390 GUI commands
      *          which may include batch commands CMD.
@@ -143,6 +143,7 @@ public  class  z390
      * 2021-04-19 jjg Replace Linux/Mac Perl usage with Linux shell
      * 2021-04-21 jjg Add CBLC, CBLCL, CBLCLG as commands
      * 2023-01-25 RPI 1598 re-implement javadoc changes by Hugh Sweeney
+     * 2024-08-12 #545 Extend generated java doco to include private methods
 	 ********************************************************
      * Global variables                  last RPI
      *****************************************************