Changeset 13358


Ignore:
Timestamp:
06/22/11 10:38:34 (11 years ago)
Author:
Mark Evenson
Message:

Convert to use @DocString? annotation adding documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/abcl/src/org/armedbear/lisp/Pathname.java

    r13353 r13358  
    6868    private volatile String namestring;
    6969
    70     /** The protocol for changing any instance field (i.e. 'host', 'type', etc.)
    71      *  is to call this method after changing the field to recompute the namestring.
    72      *  We could do this with setter/getters, but that choose not to in order to avoid the
     70    /** The protocol for changing any instance field (i.e. 'host',
     71     *  'type', etc.)  is to call this method after changing the field
     72     *  to recompute the namestring.  We could do this with
     73     *  setter/getters, but that choose not to in order to avoid the
    7374     *  performance indirection penalty.
     75     *
     76     *  TODO There is no "perfomance penalty" in contemporary
     77     *  compilers which inline such access, so it would be better to
     78     *  implement this as setter/getter ME 20110622
    7479     *
    7580     *  Although, given the number of bugs that crop up when this
    … …  
    8085    }
    8186   
    82     // ### %invalidate-namestring
    83     private static final Primitive _INVALIDATE_NAMESTRING = new pf_invalidate_namestring();
     87    private static final Primitive _INVALIDATE_NAMESTRING
     88        = new pf_invalidate_namestring();
     89    @DocString(name="%invalidate-namestring",
     90               args="pathname",
     91               returns="pathname")
    8492    private static class pf_invalidate_namestring extends Primitive {
    8593        pf_invalidate_namestring() {
    … …  
    790798    }
    791799
    792     /** @return The representation of this pathname suitable for referencing an entry in a Zip/JAR file */
     800    /** @return The representation of this pathname suitable for
     801     *  referencing an entry in a Zip/JAR file
     802     */
    793803    protected String asEntryPath() {
    794804        Pathname p = new Pathname();
    … …  
    10791089        }
    10801090    }
    1081     // ### %pathname-host
     1091
    10821092    private static final Primitive _PATHNAME_HOST = new pf_pathname_host();
     1093    @DocString(name="%pathname-host")
    10831094    private static class pf_pathname_host extends Primitive {
    10841095        pf_pathname_host() {
    … …  
    10871098        @Override
    10881099        public LispObject execute(LispObject first, LispObject second) {
    1089             checkCaseArgument(second);
     1100            checkCaseArgument(second); // FIXME Why is this ignored?
    10901101            return coerceToPathname(first).host;
    10911102        }
    10921103    }
    1093     // ### %pathname-device
    10941104    private static final Primitive _PATHNAME_DEVICE = new pf_pathname_device();
     1105    @DocString(name="%pathname-device")
    10951106    private static class pf_pathname_device extends Primitive {
    10961107        pf_pathname_device() {
    … …  
    10991110        @Override
    11001111        public LispObject execute(LispObject first, LispObject second) {
    1101             checkCaseArgument(second);
     1112            checkCaseArgument(second); // FIXME Why is this ignored?
    11021113            return coerceToPathname(first).device;
    11031114        }
    11041115    }
    1105     // ### %pathname-directory
    11061116    private static final Primitive _PATHNAME_DIRECTORY = new pf_pathname_directory();
     1117    @DocString(name="%pathname-directory")
    11071118    private static class pf_pathname_directory extends Primitive {
    11081119        pf_pathname_directory() {
    … …  
    11111122        @Override
    11121123        public LispObject execute(LispObject first, LispObject second) {
    1113             checkCaseArgument(second);
     1124            checkCaseArgument(second); // FIXME Why is this ignored?
    11141125            return coerceToPathname(first).directory;
    11151126        }
    11161127    }
    1117     // ### %pathname-name
    11181128    private static final Primitive _PATHNAME_NAME = new pf_pathname_name();
     1129    @DocString(name="%pathname-name")
    11191130    private static class  pf_pathname_name extends Primitive {
    11201131        pf_pathname_name() {
    … …  
    11231134        @Override
    11241135        public LispObject execute(LispObject first, LispObject second) {
    1125             checkCaseArgument(second);
     1136            checkCaseArgument(second); // FIXME Why is this ignored?
    11261137            return coerceToPathname(first).name;
    11271138        }
    11281139    }
    1129     // ### %pathname-type
    11301140    private static final Primitive _PATHNAME_TYPE = new pf_pathname_type();
     1141    @DocString(name="%pathname-type")
    11311142    private static class pf_pathname_type extends Primitive {
    11321143        pf_pathname_type() {
    … …  
    11351146        @Override
    11361147        public LispObject execute(LispObject first, LispObject second) {
    1137             checkCaseArgument(second);
     1148            checkCaseArgument(second); // FIXME Why is this ignored?
    11381149            return coerceToPathname(first).type;
    11391150        }
    11401151    }
    1141     // ### pathname-version
     1152   
    11421153    private static final Primitive PATHNAME_VERSION = new pf_pathname_version();
     1154    @DocString(name="pathname-version",
     1155               args="pathname",
     1156               returns="version",
     1157               doc="Return the version component of PATHNAME.")
    11431158    private static class pf_pathname_version extends Primitive {
    11441159        pf_pathname_version() {
    … …  
    11501165        }
    11511166    }
    1152     // ### namestring
    1153     // namestring pathname => namestring
    11541167    private static final Primitive NAMESTRING = new pf_namestring();
     1168    @DocString(name="namestring",
     1169               args="pathname",
     1170               returns="namestring",
     1171    doc="Returns the NAMESTRING of PATHNAME if it has one.\n"
     1172      + "\n"
     1173      + "If PATHNAME is of type url-pathname or jar-pathname the NAMESTRING is encoded\n"
     1174      + "according to the uri percent escape rules.\n"
     1175      + "\n"
     1176      + "Signals an error if PATHNAME lacks a printable NAMESTRING representation.\n")
    11551177    private static class pf_namestring extends Primitive {
    11561178        pf_namestring() {
    … …  
    11681190        }
    11691191    }
    1170     // ### directory-namestring
    1171     // directory-namestring pathname => namestring
     1192   
    11721193    private static final Primitive DIRECTORY_NAMESTRING = new pf_directory_namestring();
     1194    // TODO clarify uri encoding rules in implementation, then document
     1195    @DocString(name="directory-namestring",
     1196               args="pathname",
     1197               returns="namestring",
     1198    doc="Returns the NAMESTRING of directory porition of PATHNAME if it has one.")
    11731199    private static class pf_directory_namestring extends Primitive {
    11741200        pf_directory_namestring() {
    … …  
    11801206        }
    11811207    }
    1182     // ### pathname pathspec => pathname
    11831208    private static final Primitive PATHNAME = new pf_pathname();
     1209    @DocString(name="pathname",
     1210               args="pathspec",
     1211               returns="pathname",
     1212               doc="Returns the PATHNAME denoted by PATHSPEC.")
    11841213    private static class pf_pathname extends Primitive {
    11851214        pf_pathname() {
    … …  
    11911220        }
    11921221    }
    1193     // ### %parse-namestring string host default-pathname => pathname, position
    11941222    private static final Primitive _PARSE_NAMESTRING = new pf_parse_namestring();
     1223    @DocString(name="%parse-namestring",
     1224               args="namestring host default-pathname",
     1225               returns="pathname, position")
    11951226    private static class pf_parse_namestring extends Primitive {
    11961227        pf_parse_namestring() {
    … …  
    12231254        }
    12241255    }
    1225     // ### make-pathname
    12261256    private static final Primitive MAKE_PATHNAME = new pf_make_pathname();
     1257    @DocString(name="make-pathname",
     1258               args="&key host device directory name type version defaults case",
     1259               returns="pathname",
     1260    doc="Constructs and returns a pathname from the supplied keyword arguments.")
    12271261    private static class pf_make_pathname extends Primitive {
    12281262        pf_make_pathname() {
    … …  
    14471481        return true;
    14481482    }
    1449     // ### pathnamep
    14501483    private static final Primitive PATHNAMEP = new pf_pathnamep();
     1484    @DocString(name="pathnamep",
     1485               args="object",
     1486               returns="generalized-boolean",
     1487    doc="Returns true if OBJECT is of type pathname; otherwise, returns false.")
    14511488    private static class pf_pathnamep extends Primitive  {
    14521489        pf_pathnamep() {
    … …  
    14581495        }
    14591496    }
    1460     // ### logical-pathname-p
    14611497    private static final Primitive LOGICAL_PATHNAME_P = new pf_logical_pathname_p();
     1498    @DocString(name="logical-pathname-p",
     1499               args="object",
     1500               returns="generalized-boolean",
     1501
     1502    doc="Returns true if OBJECT is of type logical-pathname; otherwise, returns false.")
    14621503    private static class pf_logical_pathname_p extends Primitive {
    14631504        pf_logical_pathname_p() {
    … …  
    14691510        }
    14701511    }
    1471     // ### user-homedir-pathname &optional host => pathname
     1512
    14721513    private static final Primitive USER_HOMEDIR_PATHNAME = new pf_user_homedir_pathname();
     1514    @DocString(name="user-homedir-pathname",
     1515               args="&optional host",
     1516               returns="pathname",
     1517    doc="Determines the pathname that corresponds to the user's home directory.\n"
     1518      + "The value returned is obtained from the JVM system propoerty 'user.home'.\n"
     1519      + "If HOST is specified, returns NIL.")
    14731520    private static class pf_user_homedir_pathname extends Primitive {
    14741521        pf_user_homedir_pathname() {
    … …  
    14931540    }
    14941541
    1495     // ### list-directory directory
    14961542    private static final Primitive LIST_DIRECTORY = new pf_list_directory();
     1543    @DocString(name="list-directory",
     1544               args="directory &optional (resolve-symlinks t)",
     1545               returns="pathnames",
     1546    doc="Lists the contents of DIRECTORY, optionally resolving symbolic links.")
    14971547    private static class pf_list_directory extends Primitive {
    14981548        pf_list_directory() {
    … …  
    15941644    }
    15951645
    1596     // ### match-wild-jar-pathname wild-jar-pathname
     1646    @DocString(name="match-wild-jar-pathname",
     1647               args="wild-jar-pathname",
     1648               returns="pathnames",
     1649    doc="Returns the pathnames matching WILD-JAR-PATHNAME which is both wild and a jar-pathname.")
    15971650    static final Primitive MATCH_WILD_JAR_PATHNAME = new pf_match_wild_jar_pathname();
    15981651    private static class pf_match_wild_jar_pathname extends Primitive {
    … …  
    16971750    }
    16981751
    1699     // ### PATHNAME-JAR-P
     1752    @DocString(name="pathname-jar-p",
     1753               args="pathname",
     1754               returns="generalized-boolean",
     1755    doc="Predicate functionfor whether PATHNAME references a jar.")
    17001756    private static final Primitive PATHNAME_JAR_P = new pf_pathname_jar_p();
    17011757    private static class pf_pathname_jar_p extends Primitive {
    17021758        pf_pathname_jar_p() {
    1703             super("pathname-jar-p", PACKAGE_EXT, true, "pathname",
    1704                   "Predicate for whether PATHNAME references a JAR.");
     1759            super("pathname-jar-p", PACKAGE_EXT, true);
    17051760        }
    17061761        @Override
    … …  
    17151770    }
    17161771
    1717     // ### PATHNAME-URL-P
     1772    @DocString(name="pathname-url-p",
     1773               args="pathname",
     1774               returns="generalized-boolean",
     1775    doc="Predicate function for whether PATHNAME references a jaurl.")
    17181776    private static final Primitive PATHNAME_URL_P = new pf_pathname_url_p();
    17191777    private static class pf_pathname_url_p extends Primitive {
    … …  
    17821840        return false;
    17831841    }
    1784     // ### %wild-pathname-p
     1842
    17851843    private static final Primitive _WILD_PATHNAME_P = new pf_wild_pathname_p();
     1844    @DocString(name="%wild-pathname-p",
     1845               args="pathname keyword",
     1846               returns="generalized-boolean",
     1847    doc="Predicate for determing whether PATHNAME contains wild components.\n"
     1848      + "KEYWORD, if non-nil, should be one of :directory, :host, :device,\n"
     1849      + ":name, :type, or :version indicating that only the specified component\n"
     1850      + "should be checked for wildness.")
    17861851    static final class pf_wild_pathname_p extends Primitive {
    17871852        pf_wild_pathname_p() {
    … …  
    18281893    }
    18291894
    1830     // ### merge-pathnames pathname &optional default-pathname default-version"
    18311895    private static final Primitive MERGE_PATHNAMES = new pf_merge_pathnames();
     1896    @DocString(name="merge-pathnames",
     1897               args="pathname &optional default-pathname default-version",
     1898               returns="pathname",
     1899    doc="Constructs a pathname from PATHNAME by filling in any unsupplied components\n"
     1900     +  "with the corresponding values from DEFAULT-PATHNAME and DEFAULT-VERSION.")
    18321901    static final class pf_merge_pathnames extends Primitive {
    18331902        pf_merge_pathnames() {
    … …  
    23092378    }
    23102379
    2311     // ### mkdir pathname
    23122380    private static final Primitive MKDIR = new pf_mkdir();
     2381    @DocString(name="mkdir",
     2382               args="pathname",
     2383               returns="generalized-boolean",
     2384    doc="Attempts to create directory at PATHNAME returning the success or failure.")
    23132385    private static class pf_mkdir extends Primitive {
    23142386        pf_mkdir() {
    … …  
    23382410    }
    23392411
    2340     // ### rename-file filespec new-name => defaulted-new-name, old-truename, new-truename
    23412412    private static final Primitive RENAME_FILE = new pf_rename_file();
     2413    @DocString(name="rename-file",
     2414               args="filespec new-name",
     2415               returns="defaulted-new-name, old-truename, new-truename",
     2416    doc="rename-file modifies the file system in such a way that the file indicated by FILESPEC is renamed to DEFAULTED-NEW-NAME.")
    23422417    private static class pf_rename_file extends Primitive {
    23432418        pf_rename_file() {
    … …  
    23922467        }
    23932468    }
    2394 
    2395     // ### file-namestring pathname => namestring
     2469   
     2470    // TODO clarify uri encoding cases in implementation and document
    23962471    private static final Primitive FILE_NAMESTRING = new pf_file_namestring();
     2472    @DocString(name="file-namestring",
     2473               args="pathname",
     2474               returns="namestring",
     2475    doc="Returns just the name, type, and version components of PATHNAME.")
    23972476    private static class pf_file_namestring extends Primitive {
    23982477        pf_file_namestring() {
    … …  
    24202499    }
    24212500
    2422     // ### host-namestring pathname => namestring
    24232501    private static final Primitive HOST_NAMESTRING = new pf_host_namestring();
     2502    @DocString(name="host-namestring",
     2503               args="pathname",
     2504               returns="namestring",
     2505    doc="Returns the host name of PATHNAME.")
    24242506    private static class pf_host_namestring extends Primitive {
    24252507        pf_host_namestring() {
    … …  
    24642546   
    24652547    @DocString(name="uri-decode",
    2466                args="string => string",
    2467                doc="Decode percent escape sequences in the manner of URI encodings.")
     2548               args="string",
     2549               returns="string",
     2550    doc="Decode STRING percent escape sequences in the manner of URI encodings.")
    24682551    private static final Primitive URI_DECODE = new pf_uri_decode();
    24692552    private static final class pf_uri_decode extends Primitive {
    … …  
    24892572    }
    24902573   
    2491         @DocString(name="uri-encode",
    2492                args="string => string",
    2493                doc="Encode percent escape sequences in the manner of URI encodings.")
     2574    @DocString(name="uri-encode",
     2575               args="string",
     2576               returns="string",
     2577    doc="Encode percent escape sequences in the manner of URI encodings.")
    24942578    private static final Primitive URI_ENCODE = new pf_uri_encode();
    24952579    private static final class pf_uri_encode extends Primitive {
Note: See TracChangeset for help on using the changeset viewer.