From 80bf7b4fa27ea6844e39c31435c983c89d510898 Mon Sep 17 00:00:00 2001 From: Abe Kornelis Date: Wed, 14 Aug 2024 21:24:34 +0200 Subject: [PATCH] Issue#545 Extend generated java doco to include private methods (#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 | 2 +- bat/BLDJVDOC.BAT | 2 +- src/az390.java | 4 +--- src/ez390.java | 5 +++-- src/gz390.java | 7 ++++--- src/tz390.java | 11 +++++++---- src/vz390.java | 33 ++++++++++++++++++++------------- src/z390.java | 3 ++- 8 files changed, 39 insertions(+), 28 deletions(-) diff --git a/bash/bldjavadoc b/bash/bldjavadoc index 9d7e36292..857ac9fbe 100755 --- a/bash/bldjavadoc +++ b/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 diff --git a/bat/BLDJVDOC.BAT b/bat/BLDJVDOC.BAT index 168d550a4..491dac320 100644 --- a/bat/BLDJVDOC.BAT +++ b/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 diff --git a/src/az390.java b/src/az390.java index 0450ce544..d73155b86 100644 --- a/src/az390.java +++ b/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; diff --git a/src/ez390.java b/src/ez390.java index 6cc30fcf2..4100db327 100644 --- a/src/ez390.java +++ b/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 diff --git a/src/gz390.java b/src/gz390.java index 7a9417087..879dfd57c 100644 --- a/src/gz390.java +++ b/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 diff --git a/src/tz390.java b/src/tz390.java index 5f98c1132..520751e13 100644 --- a/src/tz390.java +++ b/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) /** *
    - * copy test tables to live tables - * initialize translate tables - * initialize printable character table + *
  1. copy test tables to live tables
    2. + *
  2. initialize translate tables
    3. + *
  3. initialize printable character table
    4. *
*/ 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){ diff --git a/src/vz390.java b/src/vz390.java index 66e0d5e3f..deb71bedd 100644 --- a/src/vz390.java +++ b/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 *
    *
  1. Set cur_vclra_addr
    2. - *
  2. Set cur_vptha_addr or 0
    3. + *
  3. Set cur_vptha_addr or 0 *
      *
    1. If vpth_flag_aixp, set acb_oflgs_aixp else 0
      2. *
    2. If vpth_flag_aixu, set acb_oflgs_aixu else 0
      3. @@ -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() { /** *
        - * set RPLLXRBA last rec XRBA - *
      1. VES for ESDS/RRDS
        2. - *
      2. VX0 for KSDS/VRRDS
        3. + *
      3. set RPLLXRBA last rec XRBA + *
          + *
        1. VES for ESDS/RRDS
          2. + *
        2. VX0 for KSDS/VRRDS
          3. + *
        4. *
      * @param xrba - long */ @@ -1700,9 +1704,11 @@ private void set_rpl_cxrba(long xrba) { /** *
        - * set RPLLXRBA last rec XRBA - *
      1. VES for ESDS/RRDS
        2. - *
      2. VX0 for KSDS/VRRDS
        3. + *
      3. set RPLLXRBA last rec XRBA + *
          + *
        1. VES for ESDS/RRDS
          2. + *
        2. VX0 for KSDS/VRRDS
          3. + *
        4. *
      */ private void set_rpl_ksit() { @@ -2301,11 +2307,11 @@ private boolean get_ksir_rec() { /** *
        *
      1. if random access by key rec #, then cur_vx0_rba = rec# * 8 else cur_vx0_xrba = cur_rpl_cxrba.
        2. - *
      2. Set cur_ves_xrba as follows if cur_vx0_xrba > eod set cur_vx0_xrba = -1 (not found) and return false
        3. + *
      3. Set cur_ves_xrba as follows if cur_vx0_xrba > eod set cur_vx0_xrba = -1 (not found) and return false
        4. *
      4. Set cur_ves_xrba as follows: *
          *
        1. -1 if 0 return false (no rec found)
          2. - *
        2. xrba and return true.
          3. + *
        3. xrba and return true.
          4. *
        5. *
      * 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 *
        - *
      1. If rec_len > max_vcb_lrec return false.
        2. - *
      2. search for allocated vcb If not found add new vcb up to
        3. - * max_vcb else replace least recently used allocated vcb. + *
      3. If rec_len > max_vcb_lrec return false.
        4. + *
      4. search for allocated vcb If not found add new vcb up to + * max_vcb else replace least recently used allocated vcb.
        5. *
      5. Set vcb_index and return true.
        6. *
      * @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) { diff --git a/src/z390.java b/src/z390.java index a248ee894..0dc4d14ee 100644 --- a/src/z390.java +++ b/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 *****************************************************