diff --git a/Ports/CLDC11/convert_javadocs_simple.py b/Ports/CLDC11/convert_javadocs_simple.py new file mode 100644 index 0000000000..3cde1d8f8e --- /dev/null +++ b/Ports/CLDC11/convert_javadocs_simple.py @@ -0,0 +1,520 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import fnmatch +import html +import re +from pathlib import Path +from typing import Dict, Iterable, List, Tuple + + +# ----------------------------- +# File walking +# ----------------------------- + +def iter_files(root: Path, includes: List[str], excludes: List[str]) -> Iterable[Path]: + root = root.resolve() + if root.is_file(): + yield root + return + + for p in root.rglob("*"): + if not p.is_file(): + continue + rel = p.relative_to(root).as_posix() + if includes and not any(fnmatch.fnmatch(rel, pat) for pat in includes): + continue + if any(fnmatch.fnmatch(rel, pat) for pat in excludes): + continue + yield p + + +# ----------------------------- +# Legacy JavaDoc block detection +# ----------------------------- + +def find_javadoc_blocks(source: str) -> List[Tuple[int, int]]: + blocks: List[Tuple[int, int]] = [] + + i = 0 + n = len(source) + in_string = False + in_char = False + in_line_comment = False + in_block_comment = False + + def peek(k: int) -> str: + return source[i + k] if i + k < n else "" + + while i < n: + c = source[i] + + if in_line_comment: + if c == "\n": + in_line_comment = False + i += 1 + continue + + if in_block_comment: + if c == "*" and peek(1) == "/": + in_block_comment = False + i += 2 + else: + i += 1 + continue + + if in_string: + if c == "\\": + i += 2 + continue + if c == '"': + in_string = False + i += 1 + continue + + if in_char: + if c == "\\": + i += 2 + continue + if c == "'": + in_char = False + i += 1 + continue + + if c == "/" and peek(1) == "/": + in_line_comment = True + i += 2 + continue + + if c == "/" and peek(1) == "*": + if peek(2) == "*": + start = i + j = i + 3 + while j < n - 1: + if source[j] == "*" and source[j + 1] == "/": + end = j + 2 + blocks.append((start, end)) + i = end + break + j += 1 + else: + break + continue + else: + in_block_comment = True + i += 2 + continue + + if c == '"': + in_string = True + i += 1 + continue + + if c == "'": + in_char = True + i += 1 + continue + + i += 1 + + return blocks + + +def strip_javadoc_stars(block_body: str) -> str: + lines = block_body.splitlines() + out: List[str] = [] + for line in lines: + m = re.match(r"^\s*\*\s?(.*)$", line) + out.append(m.group(1) if m else line.rstrip("\r")) + + while out and out[0].strip() == "": + out.pop(0) + while out and out[-1].strip() == "": + out.pop() + return "\n".join(out) + + +def line_start_and_indent(text: str, slash_index: int) -> Tuple[int, str]: + line_start = text.rfind("\n", 0, slash_index) + 1 + prefix = text[line_start:slash_index] + if prefix and any(ch not in (" ", "\t") for ch in prefix): + return slash_index, "" + return line_start, prefix + + +# ----------------------------- +# JavaDoc -> Markdown conversion +# ----------------------------- + +LINK_RE = re.compile(r"\{@link\s+([^}]+)\}") +CODE_RE = re.compile(r"\{@code\s+([^}]+)\}") +LITERAL_RE = re.compile(r"\{@literal\s+([^}]+)\}") + +A_TAG_RE = re.compile(r']*href="([^"]+)"[^>]*>(.*?)', re.IGNORECASE | re.DOTALL) +PRE_RE = re.compile(r"]*>(.*?)", re.IGNORECASE | re.DOTALL) +CODE_TAG_RE = re.compile(r"]*>(.*?)", re.IGNORECASE | re.DOTALL) + +BR_RE = re.compile(r"", re.IGNORECASE) +P_OPEN_RE = re.compile(r"]*>", re.IGNORECASE) +P_CLOSE_RE = re.compile(r"", re.IGNORECASE) + +B_OPEN_RE = re.compile(r"<(b|strong)\b[^>]*>", re.IGNORECASE) +B_CLOSE_RE = re.compile(r"", re.IGNORECASE) +I_OPEN_RE = re.compile(r"<(i|em)\b[^>]*>", re.IGNORECASE) +I_CLOSE_RE = re.compile(r"", re.IGNORECASE) + +UL_OPEN_RE = re.compile(r"]*>", re.IGNORECASE) +UL_CLOSE_RE = re.compile(r"", re.IGNORECASE) +OL_OPEN_RE = re.compile(r"]*>", re.IGNORECASE) +OL_CLOSE_RE = re.compile(r"", re.IGNORECASE) +LI_OPEN_RE = re.compile(r"]*>", re.IGNORECASE) +LI_CLOSE_RE = re.compile(r"", re.IGNORECASE) + +ANY_TAG_RE = re.compile(r"]+>") + +PARAM_RE = re.compile(r"^@param\s+(\S+)\s*(.*)$") +RET_RE = re.compile(r"^@return\s*(.*)$") +THROWS_RE = re.compile(r"^@(throws|exception)\s+(\S+)\s*(.*)$") +SEE_RE = re.compile(r"^@see\s*(.*)$") +SINCE_RE = re.compile(r"^@since\s*(.*)$") +DEPR_RE = re.compile(r"^@deprecated\s*(.*)$") + + +def escape_backticks(s: str) -> str: + return f"`{s}`" if "`" not in s else f"``{s}``" + + +def replace_inline_javadoc_tags(text: str) -> str: + def repl_code(m: re.Match) -> str: + return escape_backticks(html.unescape(m.group(1).strip())) + + def repl_literal(m: re.Match) -> str: + return html.unescape(m.group(1).strip()) + + def repl_link(m: re.Match) -> str: + inner = m.group(1).strip() + parts = inner.split() + if len(parts) >= 2: + label = " ".join(parts[1:]) + return escape_backticks(html.unescape(label)) + return escape_backticks(html.unescape(parts[0])) + + text = CODE_RE.sub(repl_code, text) + text = LITERAL_RE.sub(repl_literal, text) + text = LINK_RE.sub(repl_link, text) + return text + + +def convert_html_to_markdown(text: str) -> str: + def repl_pre(m: re.Match) -> str: + inner = m.group(1).strip("\n\r") + inner = CODE_TAG_RE.sub(lambda mm: mm.group(1), inner) + inner = html.unescape(inner).strip("\n\r") + return f"\n```java\n{inner}\n```\n" + + text = PRE_RE.sub(repl_pre, text) + + def repl_code_tag(m: re.Match) -> str: + inner = html.unescape(m.group(1).strip()) + inner = re.sub(r"\s+", " ", inner).strip() + return escape_backticks(inner) + + text = CODE_TAG_RE.sub(repl_code_tag, text) + + def repl_a(m: re.Match) -> str: + href = m.group(1).strip() + label = re.sub(r"\s+", " ", html.unescape(m.group(2)).strip()) + return f"[{label}]({href})" + + text = A_TAG_RE.sub(repl_a, text) + + text = B_OPEN_RE.sub("**", text) + text = B_CLOSE_RE.sub("**", text) + text = I_OPEN_RE.sub("*", text) + text = I_CLOSE_RE.sub("*", text) + + text = BR_RE.sub("\n", text) + text = P_OPEN_RE.sub("\n\n", text) + text = P_CLOSE_RE.sub("\n\n", text) + + text = UL_OPEN_RE.sub("\n", text) + text = UL_CLOSE_RE.sub("\n", text) + text = OL_OPEN_RE.sub("\n", text) + text = OL_CLOSE_RE.sub("\n", text) + text = LI_OPEN_RE.sub("\n- ", text) + text = LI_CLOSE_RE.sub("", text) + + text = ANY_TAG_RE.sub("", text) + text = html.unescape(text) + text = re.sub(r"\n{3,}", "\n\n", text) + return text.strip() + + +def parse_block_tags(lines: List[str]) -> Tuple[List[str], Dict[str, List[Tuple[str, str]]], Dict[str, str]]: + main: List[str] = [] + params: List[Tuple[str, str]] = [] + throws: List[Tuple[str, str]] = [] + see: List[Tuple[str, str]] = [] + singles: Dict[str, str] = {} + + i = 0 + n = len(lines) + + def read_continuation(start_i: int) -> Tuple[str, int]: + parts: List[str] = [] + j = start_i + while j < n: + s = lines[j] + if j == start_i: + parts.append(s) + j += 1 + continue + if s.strip() == "": + parts.append(s) + j += 1 + continue + if s.lstrip().startswith("@"): + break + parts.append(s) + j += 1 + joined = "\n".join(parts).strip() + joined = re.sub(r"\n{3,}", "\n\n", joined) + return joined, j + + while i < n: + line = lines[i] + stripped = line.lstrip() + + if stripped.startswith("@"): + if PARAM_RE.match(stripped): + name = PARAM_RE.match(stripped).group(1) + blob, i2 = read_continuation(i) + desc = PARAM_RE.sub(r"\2", blob, count=1).strip() + params.append((name, desc)) + i = i2 + continue + + if THROWS_RE.match(stripped): + exc = THROWS_RE.match(stripped).group(2) + blob, i2 = read_continuation(i) + desc = THROWS_RE.sub(r"\3", blob, count=1).strip() + throws.append((exc, desc)) + i = i2 + continue + + if RET_RE.match(stripped): + blob, i2 = read_continuation(i) + singles["return"] = RET_RE.sub(r"\1", blob, count=1).strip() + i = i2 + continue + + if SEE_RE.match(stripped): + blob, i2 = read_continuation(i) + see.append((SEE_RE.sub(r"\1", blob, count=1).strip(), "")) + i = i2 + continue + + if SINCE_RE.match(stripped): + blob, i2 = read_continuation(i) + singles["since"] = SINCE_RE.sub(r"\1", blob, count=1).strip() + i = i2 + continue + + if DEPR_RE.match(stripped): + blob, i2 = read_continuation(i) + singles["deprecated"] = DEPR_RE.sub(r"\1", blob, count=1).strip() + i = i2 + continue + + blob, i2 = read_continuation(i) + main.append(blob) + i = i2 + continue + + main.append(line) + i += 1 + + return main, {"params": params, "throws": throws, "see": see}, singles + + +def build_markdown(main_text: str, lists: Dict[str, List[Tuple[str, str]]], singles: Dict[str, str]) -> str: + parts: List[str] = [] + if main_text.strip(): + parts.append(main_text.strip()) + + params = lists.get("params") or [] + throws = lists.get("throws") or [] + see = lists.get("see") or [] + + if params: + parts.append("#### Parameters") + for name, desc in params: + parts.append(f"- `{name}`: {desc.strip()}" if desc.strip() else f"- `{name}`") + + if "return" in singles and singles["return"].strip(): + parts.append("#### Returns") + parts.append(singles["return"].strip()) + + if throws: + parts.append("#### Throws") + for exc, desc in throws: + parts.append(f"- `{exc}`: {desc.strip()}" if desc.strip() else f"- `{exc}`") + + if "since" in singles and singles["since"].strip(): + parts.append("#### Since") + parts.append(singles["since"].strip()) + + if "deprecated" in singles and singles["deprecated"].strip(): + parts.append("#### Deprecated") + parts.append(singles["deprecated"].strip()) + + if see: + parts.append("#### See also") + for item, _ in see: + item = item.strip() + if item: + parts.append(f"- {item}") + + out = "\n\n".join(p.strip() for p in parts if p.strip()) + out = re.sub(r"\n{3,}", "\n\n", out).strip() + return out + + +def cleanup_markdown_indentation(md: str) -> str: + """ + Remove accidental 4+ leading spaces on prose lines outside fenced code blocks. + This fixes cases where old JavaDoc indentation becomes Markdown code blocks. + """ + lines = md.replace("\r\n", "\n").replace("\r", "\n").split("\n") + out: List[str] = [] + in_fence = False + + for line in lines: + stripped = line.lstrip() + + if stripped.startswith("```"): + in_fence = not in_fence + out.append(line) + continue + + if in_fence: + out.append(line) + continue + + if line.startswith(" "): + out.append(line.lstrip()) + else: + out.append(line) + + text = "\n".join(out) + text = re.sub(r"\n{3,}", "\n\n", text) + return text.strip() + + +def convert_legacy_javadoc_to_md(raw: str) -> str: + raw = replace_inline_javadoc_tags(raw) + raw = convert_html_to_markdown(raw) + + lines = raw.splitlines() + main_lines, lists, singles = parse_block_tags(lines) + + main_text = "\n".join(main_lines).strip() + out = build_markdown(main_text, lists, singles) + out = cleanup_markdown_indentation(out) + return "\n".join(ln.rstrip() for ln in out.splitlines()).strip() + + +# ----------------------------- +# Emit Java 25 /// comments +# ----------------------------- + +def render_triple_slash_doc(md: str, indent: str) -> str: + lines = md.replace("\r\n", "\n").replace("\r", "\n").split("\n") + if lines == [""]: + return f"{indent}///" + + out: List[str] = [] + for ln in lines: + if ln == "": + out.append(f"{indent}///") + else: + out.append(f"{indent}/// {ln}") + return "\n".join(out) + + +# ----------------------------- +# File conversion +# ----------------------------- + +def convert_file_in_place(path: Path, dry_run: bool = False) -> bool: + try: + src = path.read_text(encoding="utf-8") + except UnicodeDecodeError: + return False + + blocks = find_javadoc_blocks(src) + if not blocks: + return False + + out = src + + for start, end in reversed(blocks): + replace_start, indent = line_start_and_indent(out, start) + + legacy_block = out[start:end] + normalized = legacy_block.replace("\r\n", "\n").replace("\r", "\n") + + header_idx = normalized.find("/**") + if header_idx == -1: + continue + + inner_body = normalized[header_idx + 3 : -2] + raw_content = strip_javadoc_stars(inner_body) + + md = convert_legacy_javadoc_to_md(raw_content) + triple = render_triple_slash_doc(md, indent) + + out = out[:replace_start] + triple + out[end:] + + if out != src: + if not dry_run: + path.write_text(out, encoding="utf-8", newline="\n") + return True + + return False + + +# ----------------------------- +# Main +# ----------------------------- + +def main() -> None: + ap = argparse.ArgumentParser( + description="Convert legacy /** ... */ JavaDoc to Java 25 /// Markdown doc comments." + ) + ap.add_argument("root", help="Root directory or single .java file") + ap.add_argument("--include", action="append", default=["**/*.java"], help='Include glob(s), default: "**/*.java"') + ap.add_argument("--exclude", action="append", default=[], help='Exclude glob(s), e.g. "**/build/**"') + ap.add_argument("--dry-run", action="store_true", help="Report changes but do not write files") + args = ap.parse_args() + + root = Path(args.root) + + scanned = 0 + changed = 0 + + for f in iter_files(root, args.include, args.exclude): + scanned += 1 + if convert_file_in_place(f, args.dry_run): + changed += 1 + print(f"CHANGED: {f}") + + if args.dry_run: + print(f"\nDry run complete. Scanned {scanned} file(s), would change {changed}.") + else: + print(f"\nDone. Scanned {scanned} file(s), changed {changed}.") + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/Ports/CLDC11/src/java/io/ByteArrayInputStream.java b/Ports/CLDC11/src/java/io/ByteArrayInputStream.java index 33d7362986..46e921b6de 100644 --- a/Ports/CLDC11/src/java/io/ByteArrayInputStream.java +++ b/Ports/CLDC11/src/java/io/ByteArrayInputStream.java @@ -22,104 +22,74 @@ * have any questions. */ package java.io; -/** - * A ByteArrayInputStream contains an internal buffer that contains bytes that may be read from the stream. An internal counter keeps track of the next byte to be supplied by the read method. - * Since: JDK1.0, CLDC 1.0 - */ +/// A ByteArrayInputStream contains an internal buffer that contains bytes that may be read from the stream. An internal counter keeps track of the next byte to be supplied by the read method. +/// Since: JDK1.0, CLDC 1.0 public class ByteArrayInputStream extends java.io.InputStream{ - /** - * An array of bytes that was provided by the creator of the stream. Elements buf[0] through buf[count-1] are the only bytes that can ever be read from the stream; element buf[pos] is the next byte to be read. - */ + /// An array of bytes that was provided by the creator of the stream. Elements buf[0] through buf[count-1] are the only bytes that can ever be read from the stream; element buf[pos] is the next byte to be read. protected byte[] buf; - /** - * The index one greater than the last valid character in the input stream buffer. This value should always be nonnegative and not larger than the length of buf. It is one greater than the position of the last byte within buf that can ever be read from the input stream buffer. - */ + /// The index one greater than the last valid character in the input stream buffer. This value should always be nonnegative and not larger than the length of buf. It is one greater than the position of the last byte within buf that can ever be read from the input stream buffer. protected int count; - /** - * The currently marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by the mark() method. The current buffer position is set to this point by the reset() method. - * Since: JDK1.1 - */ + /// The currently marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by the mark() method. The current buffer position is set to this point by the reset() method. + /// Since: JDK1.1 protected int mark; - /** - * The index of the next character to read from the input stream buffer. This value should always be nonnegative and not larger than the value of count. The next byte to be read from the input stream buffer will be buf[pos]. - */ + /// The index of the next character to read from the input stream buffer. This value should always be nonnegative and not larger than the value of count. The next byte to be read from the input stream buffer will be buf[pos]. protected int pos; - /** - * Creates a ByteArrayInputStream so that it uses buf as its buffer array. The buffer array is not copied. The initial value of pos is 0 and the initial value of count is the length of buf. - * buf - the input buffer. - */ + /// Creates a ByteArrayInputStream so that it uses buf as its buffer array. The buffer array is not copied. The initial value of pos is 0 and the initial value of count is the length of buf. + /// buf - the input buffer. public ByteArrayInputStream(byte[] buf){ //TODO codavaj!! } - /** - * Creates ByteArrayInputStream that uses buf as its buffer array. The initial value of pos is offset and the initial value of count is offset+length. The buffer array is not copied. - * Note that if bytes are simply read from the resulting input stream, elements buf[pos] through buf[pos+len-1] will be read; however, if a reset operation is performed, then bytes buf[0] through buf[pos-1] will then become available for input. - * buf - the input buffer.offset - the offset in the buffer of the first byte to read.length - the maximum number of bytes to read from the buffer. - */ + /// Creates ByteArrayInputStream that uses buf as its buffer array. The initial value of pos is offset and the initial value of count is offset+length. The buffer array is not copied. + /// Note that if bytes are simply read from the resulting input stream, elements buf[pos] through buf[pos+len-1] will be read; however, if a reset operation is performed, then bytes buf[0] through buf[pos-1] will then become available for input. + /// buf - the input buffer.offset - the offset in the buffer of the first byte to read.length - the maximum number of bytes to read from the buffer. public ByteArrayInputStream(byte[] buf, int offset, int length){ //TODO codavaj!! } - /** - * Returns the number of bytes that can be read from this input stream without blocking. The value returned is count - * - pos, which is the number of bytes remaining to be read from the input buffer. - */ + /// Returns the number of bytes that can be read from this input stream without blocking. The value returned is count + /// - pos, which is the number of bytes remaining to be read from the input buffer. public int available(){ return 0; //TODO codavaj!! } - /** - * Closes this input stream and releases any system resources associated with the stream. - */ + /// Closes this input stream and releases any system resources associated with the stream. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Set the current marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by this method. - */ + /// Set the current marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by this method. public void mark(int readAheadLimit){ return; //TODO codavaj!! } - /** - * Tests if ByteArrayInputStream supports mark/reset. - */ + /// Tests if ByteArrayInputStream supports mark/reset. public boolean markSupported(){ return false; //TODO codavaj!! } - /** - * Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. - * This read method cannot block. - */ + /// Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. + /// This read method cannot block. public int read(){ return 0; //TODO codavaj!! } - /** - * Reads up to len bytes of data into an array of bytes from this input stream. If pos equals count, then -1 is returned to indicate end of file. Otherwise, the number k of bytes read is equal to the smaller of len and count-pos. If k is positive, then bytes buf[pos] through buf[pos+k-1] are copied into b[off] through b[off+k-1] in the manner performed by System.arraycopy. The value k is added into pos and k is returned. - * This read method cannot block. - */ + /// Reads up to len bytes of data into an array of bytes from this input stream. If pos equals count, then -1 is returned to indicate end of file. Otherwise, the number k of bytes read is equal to the smaller of len and count-pos. If k is positive, then bytes buf[pos] through buf[pos+k-1] are copied into b[off] through b[off+k-1] in the manner performed by System.arraycopy. The value k is added into pos and k is returned. + /// This read method cannot block. public int read(byte[] b, int off, int len){ return 0; //TODO codavaj!! } - /** - * Resets the buffer to the marked position. The marked position is the beginning unless another position was marked. The value of pos is set to 0. - */ + /// Resets the buffer to the marked position. The marked position is the beginning unless another position was marked. The value of pos is set to 0. public void reset(){ return; //TODO codavaj!! } - /** - * Skips n bytes of input from this input stream. Fewer bytes might be skipped if the end of the input stream is reached. The actual number k of bytes to be skipped is equal to the smaller of n and count-pos. The value k is added into pos and k is returned. - */ + /// Skips n bytes of input from this input stream. Fewer bytes might be skipped if the end of the input stream is reached. The actual number k of bytes to be skipped is equal to the smaller of n and count-pos. The value k is added into pos and k is returned. public long skip(long n){ return 0l; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/ByteArrayOutputStream.java b/Ports/CLDC11/src/java/io/ByteArrayOutputStream.java index 17148f9c72..f03c1ddb04 100644 --- a/Ports/CLDC11/src/java/io/ByteArrayOutputStream.java +++ b/Ports/CLDC11/src/java/io/ByteArrayOutputStream.java @@ -22,82 +22,58 @@ * have any questions. */ package java.io; -/** - * This class implements an output stream in which the data is written into a byte array. The buffer automatically grows as data is written to it. The data can be retrieved using toByteArray() and toString(). - * Since: JDK1.0, CLDC 1.0 - */ +/// This class implements an output stream in which the data is written into a byte array. The buffer automatically grows as data is written to it. The data can be retrieved using toByteArray() and toString(). +/// Since: JDK1.0, CLDC 1.0 public class ByteArrayOutputStream extends java.io.OutputStream{ - /** - * The buffer where data is stored. - */ + /// The buffer where data is stored. protected byte[] buf; - /** - * The number of valid bytes in the buffer. - */ + /// The number of valid bytes in the buffer. protected int count; - /** - * Creates a new byte array output stream. The buffer capacity is initially 32 bytes, though its size increases if necessary. - */ + /// Creates a new byte array output stream. The buffer capacity is initially 32 bytes, though its size increases if necessary. public ByteArrayOutputStream(){ //TODO codavaj!! } - /** - * Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes. - * size - the initial size. - * - if size is negative. - */ + /// Creates a new byte array output stream, with a buffer capacity of the specified size, in bytes. + /// size - the initial size. + /// - if size is negative. public ByteArrayOutputStream(int size){ //TODO codavaj!! } - /** - * Closes this output stream and releases any system resources associated with this stream. A closed stream cannot perform output operations and cannot be reopened. - */ + /// Closes this output stream and releases any system resources associated with this stream. A closed stream cannot perform output operations and cannot be reopened. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Resets the count field of this byte array output stream to zero, so that all currently accumulated output in the output stream is discarded. The output stream can be used again, reusing the already allocated buffer space. - */ + /// Resets the count field of this byte array output stream to zero, so that all currently accumulated output in the output stream is discarded. The output stream can be used again, reusing the already allocated buffer space. public void reset(){ return; //TODO codavaj!! } - /** - * Returns the current size of the buffer. - */ + /// Returns the current size of the buffer. public int size(){ return 0; //TODO codavaj!! } - /** - * Creates a newly allocated byte array. Its size is the current size of this output stream and the valid contents of the buffer have been copied into it. - */ + /// Creates a newly allocated byte array. Its size is the current size of this output stream and the valid contents of the buffer have been copied into it. public byte[] toByteArray(){ return null; //TODO codavaj!! } - /** - * Converts the buffer's contents into a string, translating bytes into characters according to the platform's default character encoding. - */ + /// Converts the buffer's contents into a string, translating bytes into characters according to the platform's default character encoding. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Writes len bytes from the specified byte array starting at offset off to this byte array output stream. - */ + /// Writes len bytes from the specified byte array starting at offset off to this byte array output stream. public void write(byte[] b, int off, int len){ return; //TODO codavaj!! } - /** - * Writes the specified byte to this byte array output stream. - */ + /// Writes the specified byte to this byte array output stream. public void write(int b){ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/DataInput.java b/Ports/CLDC11/src/java/io/DataInput.java index 7219b11868..d6585c7f2b 100644 --- a/Ports/CLDC11/src/java/io/DataInput.java +++ b/Ports/CLDC11/src/java/io/DataInput.java @@ -22,100 +22,70 @@ * have any questions. */ package java.io; -/** - * The DataInput interface provides for reading bytes from a binary stream and reconstructing from them data in any of the Java primitive types. There is also a facility for reconstructing a String from data in Java modified UTF-8 format. - * It is generally true of all the reading routines in this interface that if end of file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the input stream has been closed. - * Since: JDK1.0, CLDC 1.0 See Also:DataInputStream, DataOutput - */ +/// The DataInput interface provides for reading bytes from a binary stream and reconstructing from them data in any of the Java primitive types. There is also a facility for reconstructing a String from data in Java modified UTF-8 format. +/// It is generally true of all the reading routines in this interface that if end of file is reached before the desired number of bytes has been read, an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file, an IOException other than EOFException is thrown. In particular, an IOException may be thrown if the input stream has been closed. +/// Since: JDK1.0, CLDC 1.0 See Also:DataInputStream, DataOutput public interface DataInput extends AutoCloseable { - /** - * Reads one input byte and returns true if that byte is nonzero, false if that byte is zero. This method is suitable for reading the byte written by the writeBoolean method of interface DataOutput. - */ + /// Reads one input byte and returns true if that byte is nonzero, false if that byte is zero. This method is suitable for reading the byte written by the writeBoolean method of interface DataOutput. public abstract boolean readBoolean() throws java.io.IOException; - /** - * Reads and returns one input byte. The byte is treated as a signed value in the range -128 through 127, inclusive. This method is suitable for reading the byte written by the writeByte method of interface DataOutput. - */ + /// Reads and returns one input byte. The byte is treated as a signed value in the range -128 through 127, inclusive. This method is suitable for reading the byte written by the writeByte method of interface DataOutput. public abstract byte readByte() throws java.io.IOException; - /** - * Reads an input char and returns the char value. A Unicode char is made up of two bytes. Let a be the first byte read and b be the second byte. The value returned is: - * (char)((a 8) | (b 0xff)) This method is suitable for reading bytes written by the writeChar method of interface DataOutput. - */ + /// Reads an input char and returns the char value. A Unicode char is made up of two bytes. Let a be the first byte read and b be the second byte. The value returned is: + /// (char)((a 8) | (b 0xff)) This method is suitable for reading bytes written by the writeChar method of interface DataOutput. public abstract char readChar() throws java.io.IOException; - /** - * Reads eight input bytes and returns a double value. It does this by first constructing a long value in exactly the manner of the readlong method, then converting this long value to a double in exactly the manner of the method Double.longBitsToDouble. This method is suitable for reading bytes written by the writeDouble method of interface DataOutput. - */ + /// Reads eight input bytes and returns a double value. It does this by first constructing a long value in exactly the manner of the readlong method, then converting this long value to a double in exactly the manner of the method Double.longBitsToDouble. This method is suitable for reading bytes written by the writeDouble method of interface DataOutput. public abstract double readDouble() throws java.io.IOException; - /** - * Reads four input bytes and returns a float value. It does this by first constructing an int value in exactly the manner of the readInt method, then converting this int value to a float in exactly the manner of the method Float.intBitsToFloat. This method is suitable for reading bytes written by the writeFloat method of interface DataOutput. - */ + /// Reads four input bytes and returns a float value. It does this by first constructing an int value in exactly the manner of the readInt method, then converting this int value to a float in exactly the manner of the method Float.intBitsToFloat. This method is suitable for reading bytes written by the writeFloat method of interface DataOutput. public abstract float readFloat() throws java.io.IOException; - /** - * Reads some bytes from an input stream and stores them into the buffer array b. The number of bytes read is equal to the length of b. - * This method blocks until one of the following conditions occurs: - * b.length bytes of input data are available, in which case a normal return is made. End of file is detected, in which case an EOFException is thrown. An I/O error occurs, in which case an IOException other than EOFException is thrown. - * If b is null, a NullPointerException is thrown. If b.length is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[0], the next one into b[1], and so on. If an exception is thrown from this method, then it may be that some but not all bytes of b have been updated with data from the input stream. - */ + /// Reads some bytes from an input stream and stores them into the buffer array b. The number of bytes read is equal to the length of b. + /// This method blocks until one of the following conditions occurs: + /// b.length bytes of input data are available, in which case a normal return is made. End of file is detected, in which case an EOFException is thrown. An I/O error occurs, in which case an IOException other than EOFException is thrown. + /// If b is null, a NullPointerException is thrown. If b.length is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[0], the next one into b[1], and so on. If an exception is thrown from this method, then it may be that some but not all bytes of b have been updated with data from the input stream. public abstract void readFully(byte[] b) throws java.io.IOException; - /** - * Reads len bytes from an input stream. - * This method blocks until one of the following conditions occurs: - * len bytes of input data are available, in which case a normal return is made. End of file is detected, in which case an EOFException is thrown. An I/O error occurs, in which case an IOException other than EOFException is thrown. - * If b is null, a NullPointerException is thrown. If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If len is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. - */ + /// Reads len bytes from an input stream. + /// This method blocks until one of the following conditions occurs: + /// len bytes of input data are available, in which case a normal return is made. End of file is detected, in which case an EOFException is thrown. An I/O error occurs, in which case an IOException other than EOFException is thrown. + /// If b is null, a NullPointerException is thrown. If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If len is zero, then no bytes are read. Otherwise, the first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. public abstract void readFully(byte[] b, int off, int len) throws java.io.IOException; - /** - * Reads four input bytes and returns an int value. Let a be the first byte read, b be the second byte, c be the third byte, and d be the fourth byte. The value returned is: - * (((a 0xff) 24) | ((b 0xff) 16) | ((c 0xff) 8) | (d 0xff)) This method is suitable for reading bytes written by the writeInt method of interface DataOutput. - */ + /// Reads four input bytes and returns an int value. Let a be the first byte read, b be the second byte, c be the third byte, and d be the fourth byte. The value returned is: + /// (((a 0xff) 24) | ((b 0xff) 16) | ((c 0xff) 8) | (d 0xff)) This method is suitable for reading bytes written by the writeInt method of interface DataOutput. public abstract int readInt() throws java.io.IOException; - /** - * Reads eight input bytes and returns a long value. Let a be the first byte read, b be the second byte, c be the third byte, d be the fourth byte, e be the fifth byte, f be the sixth byte, g be the seventh byte, and h be the eighth byte. The value returned is: - * (((long)(a 0xff) 56) | ((long)(b 0xff) 48) | ((long)(c 0xff) 40) | ((long)(d 0xff) 32) | ((long)(e 0xff) 24) | ((long)(f 0xff) 16) | ((long)(g 0xff) 8) | ((long)(h 0xff))) - * This method is suitable for reading bytes written by the writeLong method of interface DataOutput. - */ + /// Reads eight input bytes and returns a long value. Let a be the first byte read, b be the second byte, c be the third byte, d be the fourth byte, e be the fifth byte, f be the sixth byte, g be the seventh byte, and h be the eighth byte. The value returned is: + /// (((long)(a 0xff) 56) | ((long)(b 0xff) 48) | ((long)(c 0xff) 40) | ((long)(d 0xff) 32) | ((long)(e 0xff) 24) | ((long)(f 0xff) 16) | ((long)(g 0xff) 8) | ((long)(h 0xff))) + /// This method is suitable for reading bytes written by the writeLong method of interface DataOutput. public abstract long readLong() throws java.io.IOException; - /** - * Reads two input bytes and returns a short value. Let a be the first byte read and b be the second byte. The value returned is: - * (short)((a 8) | (b 0xff)) This method is suitable for reading the bytes written by the writeShort method of interface DataOutput. - */ + /// Reads two input bytes and returns a short value. Let a be the first byte read and b be the second byte. The value returned is: + /// (short)((a 8) | (b 0xff)) This method is suitable for reading the bytes written by the writeShort method of interface DataOutput. public abstract short readShort() throws java.io.IOException; - /** - * Reads one input byte, zero-extends it to type int, and returns the result, which is therefore in the range 0 through 255. This method is suitable for reading the byte written by the writeByte method of interface DataOutput if the argument to writeByte was intended to be a value in the range 0 through 255. - */ + /// Reads one input byte, zero-extends it to type int, and returns the result, which is therefore in the range 0 through 255. This method is suitable for reading the byte written by the writeByte method of interface DataOutput if the argument to writeByte was intended to be a value in the range 0 through 255. public abstract int readUnsignedByte() throws java.io.IOException; - /** - * Reads two input bytes, zero-extends it to type int, and returns an int value in the range 0 through 65535. Let a be the first byte read and b be the second byte. The value returned is: - * (((a 0xff) 8) | (b 0xff)) This method is suitable for reading the bytes written by the writeShort method of interface DataOutput if the argument to writeShort was intended to be a value in the range 0 through 65535. - */ + /// Reads two input bytes, zero-extends it to type int, and returns an int value in the range 0 through 65535. Let a be the first byte read and b be the second byte. The value returned is: + /// (((a 0xff) 8) | (b 0xff)) This method is suitable for reading the bytes written by the writeShort method of interface DataOutput if the argument to writeShort was intended to be a value in the range 0 through 65535. public abstract int readUnsignedShort() throws java.io.IOException; - /** - * Reads in a string that has been encoded using a modified UTF-8 format. The general contract of readUTF is that it reads a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String. - * First, two bytes are read and used to construct an unsigned 16-bit integer in exactly the manner of the readUnsignedShort method . This integer value is called the UTF length and specifies the number of additional bytes to be read. These bytes are then converted to characters by considering them in groups. The length of each group is computed from the value of the first byte of the group. The byte following a group, if any, is the first byte of the next group. - * If the first byte of a group matches the bit pattern 0xxxxxxx (where x means "may be 0 or 1"), then the group consists of just that byte. The byte is zero-extended to form a character. - * If the first byte of a group matches the bit pattern 110xxxxx, then the group consists of that byte a and a second byte b. If there is no byte b (because byte a was the last of the bytes to be read), or if byte b does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character: - * (char)(((a 0x1F) 6) | (b 0x3F)) If the first byte of a group matches the bit pattern 1110xxxx, then the group consists of that byte a and two more bytes b and c. If there is no byte c (because byte a was one of the last two of the bytes to be read), or either byte b or byte c does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character: - * (char)(((a 0x0F) 12) | ((b 0x3F) 6) | (c 0x3F)) If the first byte of a group matches the pattern 1111xxxx or the pattern 10xxxxxx, then a UTFDataFormatException is thrown. - * If end of file is encountered at any time during this entire process, then an EOFException is thrown. - * After every group has been converted to a character by this process, the characters are gathered, in the same order in which their corresponding groups were read from the input stream, to form a String, which is returned. - * The writeUTF method of interface DataOutput may be used to write data that is suitable for reading by this method. - */ + /// Reads in a string that has been encoded using a modified UTF-8 format. The general contract of readUTF is that it reads a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String. + /// First, two bytes are read and used to construct an unsigned 16-bit integer in exactly the manner of the readUnsignedShort method . This integer value is called the UTF length and specifies the number of additional bytes to be read. These bytes are then converted to characters by considering them in groups. The length of each group is computed from the value of the first byte of the group. The byte following a group, if any, is the first byte of the next group. + /// If the first byte of a group matches the bit pattern 0xxxxxxx (where x means "may be 0 or 1"), then the group consists of just that byte. The byte is zero-extended to form a character. + /// If the first byte of a group matches the bit pattern 110xxxxx, then the group consists of that byte a and a second byte b. If there is no byte b (because byte a was the last of the bytes to be read), or if byte b does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character: + /// (char)(((a 0x1F) 6) | (b 0x3F)) If the first byte of a group matches the bit pattern 1110xxxx, then the group consists of that byte a and two more bytes b and c. If there is no byte c (because byte a was one of the last two of the bytes to be read), or either byte b or byte c does not match the bit pattern 10xxxxxx, then a UTFDataFormatException is thrown. Otherwise, the group is converted to the character: + /// (char)(((a 0x0F) 12) | ((b 0x3F) 6) | (c 0x3F)) If the first byte of a group matches the pattern 1111xxxx or the pattern 10xxxxxx, then a UTFDataFormatException is thrown. + /// If end of file is encountered at any time during this entire process, then an EOFException is thrown. + /// After every group has been converted to a character by this process, the characters are gathered, in the same order in which their corresponding groups were read from the input stream, to form a String, which is returned. + /// The writeUTF method of interface DataOutput may be used to write data that is suitable for reading by this method. public abstract java.lang.String readUTF() throws java.io.IOException; - /** - * Makes an attempt to skip over n bytes of data from the input stream, discarding the skipped bytes. However, it may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. This method never throws an EOFException. The actual number of bytes skipped is returned. - */ + /// Makes an attempt to skip over n bytes of data from the input stream, discarding the skipped bytes. However, it may skip over some smaller number of bytes, possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. This method never throws an EOFException. The actual number of bytes skipped is returned. public abstract int skipBytes(int n) throws java.io.IOException; } diff --git a/Ports/CLDC11/src/java/io/DataInputStream.java b/Ports/CLDC11/src/java/io/DataInputStream.java index b1db9c1873..8e0a8a6588 100644 --- a/Ports/CLDC11/src/java/io/DataInputStream.java +++ b/Ports/CLDC11/src/java/io/DataInputStream.java @@ -22,211 +22,157 @@ * have any questions. */ package java.io; -/** - * A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. An application uses a data output stream to write data that can later be read by a data input stream. - * Since: JDK1.0, CLDC 1.0 See Also:DataOutputStream - */ +/// A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. An application uses a data output stream to write data that can later be read by a data input stream. +/// Since: JDK1.0, CLDC 1.0 See Also:DataOutputStream public class DataInputStream extends java.io.InputStream implements java.io.DataInput{ - /** - * The input stream. - */ + /// The input stream. protected java.io.InputStream in; - /** - * Creates a DataInputStream and saves its argument, the input stream in, for later use. - * in - the input stream. - */ + /// Creates a DataInputStream and saves its argument, the input stream in, for later use. + /// in - the input stream. public DataInputStream(java.io.InputStream in){ //TODO codavaj!! } - /** - * Returns the number of bytes that can be read from this input stream without blocking. - * This method simply performs in.available() and returns the result. - */ + /// Returns the number of bytes that can be read from this input stream without blocking. + /// This method simply performs in.available() and returns the result. public int available() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Closes this input stream and releases any system resources associated with the stream. This method simply performs in.close(). - */ + /// Closes this input stream and releases any system resources associated with the stream. This method simply performs in.close(). public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. - * The readlimit argument tells this input stream to allow that many bytes to be read before the mark position gets invalidated. - * This method simply performs in.mark(readlimit). - */ + /// Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. + /// The readlimit argument tells this input stream to allow that many bytes to be read before the mark position gets invalidated. + /// This method simply performs in.mark(readlimit). public void mark(int readlimit){ return; //TODO codavaj!! } - /** - * Tests if this input stream supports the mark and reset methods. This method simply performs in.markSupported(). - */ + /// Tests if this input stream supports the mark and reset methods. This method simply performs in.markSupported(). public boolean markSupported(){ return false; //TODO codavaj!! } - /** - * Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown. - * This method simply performs in.read() and returns the result. - */ + /// Reads the next byte of data from this input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown. + /// This method simply performs in.read() and returns the result. public int read() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the read method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the read method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final int read(byte[] b) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available. - * This method simply performs in.read(b, off, len) and returns the result. - */ + /// Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until some input is available. + /// This method simply performs in.read(b, off, len) and returns the result. public final int read(byte[] b, int off, int len) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readBoolean method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readBoolean method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final boolean readBoolean() throws java.io.IOException{ return false; //TODO codavaj!! } - /** - * See the general contract of the readByte method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readByte method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final byte readByte() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readChar method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readChar method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final char readChar() throws java.io.IOException{ return ' '; //TODO codavaj!! } - /** - * See the general contract of the readDouble method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readDouble method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final double readDouble() throws java.io.IOException{ return 0.0d; //TODO codavaj!! } - /** - * See the general contract of the readFloat method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readFloat method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final float readFloat() throws java.io.IOException{ return 0.0f; //TODO codavaj!! } - /** - * See the general contract of the readFully method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readFully method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final void readFully(byte[] b) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * See the general contract of the readFully method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readFully method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final void readFully(byte[] b, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * See the general contract of the readInt method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readInt method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final int readInt() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readLong method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readLong method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final long readLong() throws java.io.IOException{ return 0l; //TODO codavaj!! } - /** - * See the general contract of the readShort method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readShort method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final short readShort() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readUnsignedByte method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readUnsignedByte method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final int readUnsignedByte() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readUnsignedShort method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readUnsignedShort method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final int readUnsignedShort() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * See the general contract of the readUTF method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the readUTF method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final java.lang.String readUTF() throws java.io.IOException{ return null; //TODO codavaj!! } - /** - * Reads from the stream in a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String. The details of the modified UTF-8 representation are exactly the same as for the readUTF method of DataInput. - */ + /// Reads from the stream in a representation of a Unicode character string encoded in Java modified UTF-8 format; this string of characters is then returned as a String. The details of the modified UTF-8 representation are exactly the same as for the readUTF method of DataInput. public static final java.lang.String readUTF(java.io.DataInput in) throws java.io.IOException{ return null; //TODO codavaj!! } - /** - * Repositions this stream to the position at the time the mark method was last called on this input stream. - * This method simply performs in.reset(). - * Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parse, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails. If this happens within readlimit bytes, it allows the outer code to reset the stream and try another parser. - */ + /// Repositions this stream to the position at the time the mark method was last called on this input stream. + /// This method simply performs in.reset(). + /// Stream marks are intended to be used in situations where you need to read ahead a little to see what's in the stream. Often this is most easily done by invoking some general parser. If the stream is of the type handled by the parse, it just chugs along happily. If the stream is not of that type, the parser should toss an exception when it fails. If this happens within readlimit bytes, it allows the outer code to reset the stream and try another parser. public void reset() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned. - * This method simply performs in.skip(n). - */ + /// Skips over and discards n bytes of data from the input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. The actual number of bytes skipped is returned. + /// This method simply performs in.skip(n). public long skip(long n) throws java.io.IOException{ return 0l; //TODO codavaj!! } - /** - * See the general contract of the skipBytes method of DataInput. - * Bytes for this operation are read from the contained input stream. - */ + /// See the general contract of the skipBytes method of DataInput. + /// Bytes for this operation are read from the contained input stream. public final int skipBytes(int n) throws java.io.IOException{ return 0; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/DataOutput.java b/Ports/CLDC11/src/java/io/DataOutput.java index 3cbe73914e..41ae0ec070 100644 --- a/Ports/CLDC11/src/java/io/DataOutput.java +++ b/Ports/CLDC11/src/java/io/DataOutput.java @@ -22,91 +22,63 @@ * have any questions. */ package java.io; -/** - * The DataOutput interface provides for converting data from any of the Java primitive types to a series of bytes and writing these bytes to a binary stream. There is also a facility for converting a String into Java modified UTF-8 format and writing the resulting series of bytes. - * For all the methods in this interface that write bytes, it is generally true that if a byte cannot be written for any reason, an IOException is thrown. - * Since: JDK1.0, CLDC 1.0 See Also:DataInput, DataOutputStream - */ +/// The DataOutput interface provides for converting data from any of the Java primitive types to a series of bytes and writing these bytes to a binary stream. There is also a facility for converting a String into Java modified UTF-8 format and writing the resulting series of bytes. +/// For all the methods in this interface that write bytes, it is generally true that if a byte cannot be written for any reason, an IOException is thrown. +/// Since: JDK1.0, CLDC 1.0 See Also:DataInput, DataOutputStream public interface DataOutput extends AutoCloseable { - /** - * Writes to the output stream all the bytes in array b. If b is null, a NullPointerException is thrown. If b.length is zero, then no bytes are written. Otherwise, the byte b[0] is written first, then b[1], and so on; the last byte written is b[b.length-1]. - */ + /// Writes to the output stream all the bytes in array b. If b is null, a NullPointerException is thrown. If b.length is zero, then no bytes are written. Otherwise, the byte b[0] is written first, then b[1], and so on; the last byte written is b[b.length-1]. public abstract void write(byte[] b) throws java.io.IOException; - /** - * Writes len bytes from array b, in order, to the output stream. If b is null, a NullPointerException is thrown. If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If len is zero, then no bytes are written. Otherwise, the byte b[off] is written first, then b[off+1], and so on; the last byte written is b[off+len-1]. - */ + /// Writes len bytes from array b, in order, to the output stream. If b is null, a NullPointerException is thrown. If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. If len is zero, then no bytes are written. Otherwise, the byte b[off] is written first, then b[off+1], and so on; the last byte written is b[off+len-1]. public abstract void write(byte[] b, int off, int len) throws java.io.IOException; - /** - * Writes to the output stream the eight low-order bits of the argument b. The 24 high-order bits of b are ignored. - */ + /// Writes to the output stream the eight low-order bits of the argument b. The 24 high-order bits of b are ignored. public abstract void write(int b) throws java.io.IOException; - /** - * Writes a boolean value to this output stream. If the argument v is true, the value (byte)1 is written; if v is false, the value (byte)0 is written. The byte written by this method may be read by the readBoolean method of interface DataInput, which will then return a boolean equal to v. - */ + /// Writes a boolean value to this output stream. If the argument v is true, the value (byte)1 is written; if v is false, the value (byte)0 is written. The byte written by this method may be read by the readBoolean method of interface DataInput, which will then return a boolean equal to v. public abstract void writeBoolean(boolean v) throws java.io.IOException; - /** - * Writes to the output stream the eight low- order bits of the argument v. The 24 high-order bits of v are ignored. (This means that writeByte does exactly the same thing as write for an integer argument.) The byte written by this method may be read by the readByte method of interface DataInput, which will then return a byte equal to (byte)v. - */ + /// Writes to the output stream the eight low- order bits of the argument v. The 24 high-order bits of v are ignored. (This means that writeByte does exactly the same thing as write for an integer argument.) The byte written by this method may be read by the readByte method of interface DataInput, which will then return a byte equal to (byte)v. public abstract void writeByte(int v) throws java.io.IOException; - /** - * Writes a char value, which is comprised of two bytes, to the output stream. The byte values to be written, in the order shown, are: - * (byte)(0xff (v 8)) (byte)(0xff v) - * The bytes written by this method may be read by the readChar method of interface DataInput, which will then return a char equal to (char)v. - */ + /// Writes a char value, which is comprised of two bytes, to the output stream. The byte values to be written, in the order shown, are: + /// (byte)(0xff (v 8)) (byte)(0xff v) + /// The bytes written by this method may be read by the readChar method of interface DataInput, which will then return a char equal to (char)v. public abstract void writeChar(int v) throws java.io.IOException; - /** - * Writes every character in the string s, to the output stream, in order, two bytes per character. If s is null, a NullPointerException is thrown. If s.length is zero, then no characters are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, two bytes are actually written, high-order byte first, in exactly the manner of the writeChar method. - */ + /// Writes every character in the string s, to the output stream, in order, two bytes per character. If s is null, a NullPointerException is thrown. If s.length is zero, then no characters are written. Otherwise, the character s[0] is written first, then s[1], and so on; the last character written is s[s.length-1]. For each character, two bytes are actually written, high-order byte first, in exactly the manner of the writeChar method. public abstract void writeChars(java.lang.String s) throws java.io.IOException; - /** - * Writes a double value, which is comprised of eight bytes, to the output stream. It does this as if it first converts this double value to a long in exactly the manner of the Double.doubleToLongBits method and then writes the long value in exactly the manner of the writeLong method. The bytes written by this method may be read by the readDouble method of interface DataInput, which will then return a double equal to v. - */ + /// Writes a double value, which is comprised of eight bytes, to the output stream. It does this as if it first converts this double value to a long in exactly the manner of the Double.doubleToLongBits method and then writes the long value in exactly the manner of the writeLong method. The bytes written by this method may be read by the readDouble method of interface DataInput, which will then return a double equal to v. public abstract void writeDouble(double v) throws java.io.IOException; - /** - * Writes a float value, which is comprised of four bytes, to the output stream. It does this as if it first converts this float value to an int in exactly the manner of the Float.floatToIntBits method and then writes the int value in exactly the manner of the writeInt method. The bytes written by this method may be read by the readFloat method of interface DataInput, which will then return a float equal to v. - */ + /// Writes a float value, which is comprised of four bytes, to the output stream. It does this as if it first converts this float value to an int in exactly the manner of the Float.floatToIntBits method and then writes the int value in exactly the manner of the writeInt method. The bytes written by this method may be read by the readFloat method of interface DataInput, which will then return a float equal to v. public abstract void writeFloat(float v) throws java.io.IOException; - /** - * Writes an int value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are: - * (byte)(0xff (v 24)) (byte)(0xff (v 16)) (byte)(0xff (v 8)) (byte)(0xff v) - * The bytes written by this method may be read by the readInt method of interface DataInput, which will then return an int equal to v. - */ + /// Writes an int value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are: + /// (byte)(0xff (v 24)) (byte)(0xff (v 16)) (byte)(0xff (v 8)) (byte)(0xff v) + /// The bytes written by this method may be read by the readInt method of interface DataInput, which will then return an int equal to v. public abstract void writeInt(int v) throws java.io.IOException; - /** - * Writes an long value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are: - * (byte)(0xff (v 56)) (byte)(0xff (v 48)) (byte)(0xff (v 40)) (byte)(0xff (v 32)) (byte)(0xff (v 24)) (byte)(0xff (v 16)) (byte)(0xff (v 8)) (byte)(0xff v) - * The bytes written by this method may be read by the readLong method of interface DataInput, which will then return a long equal to v. - */ + /// Writes an long value, which is comprised of four bytes, to the output stream. The byte values to be written, in the order shown, are: + /// (byte)(0xff (v 56)) (byte)(0xff (v 48)) (byte)(0xff (v 40)) (byte)(0xff (v 32)) (byte)(0xff (v 24)) (byte)(0xff (v 16)) (byte)(0xff (v 8)) (byte)(0xff v) + /// The bytes written by this method may be read by the readLong method of interface DataInput, which will then return a long equal to v. public abstract void writeLong(long v) throws java.io.IOException; - /** - * Writes two bytes to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are: - * (byte)(0xff (v 8)) (byte)(0xff v) - * The bytes written by this method may be read by the readShort method of interface DataInput, which will then return a short equal to (short)v. - */ + /// Writes two bytes to the output stream to represent the value of the argument. The byte values to be written, in the order shown, are: + /// (byte)(0xff (v 8)) (byte)(0xff v) + /// The bytes written by this method may be read by the readShort method of interface DataInput, which will then return a short equal to (short)v. public abstract void writeShort(int v) throws java.io.IOException; - /** - * Writes two bytes of length information to the output stream, followed by the Java modified UTF representation of every character in the string s. If s is null, a NullPointerException is thrown. Each character in the string s is converted to a group of one, two, or three bytes, depending on the value of the character. - * If a character c is in the range u0001 through u007f, it is represented by one byte: - * (byte)c - * If a character c is u0000 or is in the range u0080 through u07ff, then it is represented by two bytes, to be written in the order shown: - * (byte)(0xc0 | (0x1f (c 6))) (byte)(0x80 | (0x3f c)) - * If a character c is in the range u0800 through uffff, then it is represented by three bytes, to be written in the order shown: - * (byte)(0xe0 | (0x0f (c 12))) (byte)(0x80 | (0x3f (c 6))) (byte)(0x80 | (0x3f c)) - * First, the total number of bytes needed to represent all the characters of s is calculated. If this number is larger than 65535, then a UTFDataFormatError is thrown. Otherwise, this length is written to the output stream in exactly the manner of the writeShort method; after this, the one-, two-, or three-byte representation of each character in the string s is written. - * The bytes written by this method may be read by the readUTF method of interface DataInput, which will then return a String equal to s. - */ + /// Writes two bytes of length information to the output stream, followed by the Java modified UTF representation of every character in the string s. If s is null, a NullPointerException is thrown. Each character in the string s is converted to a group of one, two, or three bytes, depending on the value of the character. + /// If a character c is in the range u0001 through u007f, it is represented by one byte: + /// (byte)c + /// If a character c is u0000 or is in the range u0080 through u07ff, then it is represented by two bytes, to be written in the order shown: + /// (byte)(0xc0 | (0x1f (c 6))) (byte)(0x80 | (0x3f c)) + /// If a character c is in the range u0800 through uffff, then it is represented by three bytes, to be written in the order shown: + /// (byte)(0xe0 | (0x0f (c 12))) (byte)(0x80 | (0x3f (c 6))) (byte)(0x80 | (0x3f c)) + /// First, the total number of bytes needed to represent all the characters of s is calculated. If this number is larger than 65535, then a UTFDataFormatError is thrown. Otherwise, this length is written to the output stream in exactly the manner of the writeShort method; after this, the one-, two-, or three-byte representation of each character in the string s is written. + /// The bytes written by this method may be read by the readUTF method of interface DataInput, which will then return a String equal to s. public abstract void writeUTF(java.lang.String s) throws java.io.IOException; } diff --git a/Ports/CLDC11/src/java/io/DataOutputStream.java b/Ports/CLDC11/src/java/io/DataOutputStream.java index fe270f9d43..93837cb0e3 100644 --- a/Ports/CLDC11/src/java/io/DataOutputStream.java +++ b/Ports/CLDC11/src/java/io/DataOutputStream.java @@ -22,122 +22,88 @@ * have any questions. */ package java.io; -/** - * A data output stream lets an application write primitive Java data types to an output stream in a portable way. An application can then use a data input stream to read the data back in. - * Since: JDK1.0, CLDC 1.0 See Also:DataInputStream - */ +/// A data output stream lets an application write primitive Java data types to an output stream in a portable way. An application can then use a data input stream to read the data back in. +/// Since: JDK1.0, CLDC 1.0 See Also:DataInputStream public class DataOutputStream extends java.io.OutputStream implements java.io.DataOutput{ - /** - * The output stream. - */ + /// The output stream. protected java.io.OutputStream out; - /** - * Creates a new data output stream to write data to the specified underlying output stream. - * out - the underlying output stream, to be saved for later use. - */ + /// Creates a new data output stream to write data to the specified underlying output stream. + /// out - the underlying output stream, to be saved for later use. public DataOutputStream(java.io.OutputStream out){ //TODO codavaj!! } - /** - * Closes this output stream and releases any system resources associated with the stream. - * The close method calls its flush method, and then calls the close method of its underlying output stream. - */ + /// Closes this output stream and releases any system resources associated with the stream. + /// The close method calls its flush method, and then calls the close method of its underlying output stream. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Flushes this data output stream. This forces any buffered output bytes to be written out to the stream. - * The flush method of DataOutputStream calls the flush method of its underlying output stream. - */ + /// Flushes this data output stream. This forces any buffered output bytes to be written out to the stream. + /// The flush method of DataOutputStream calls the flush method of its underlying output stream. public void flush() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes len bytes from the specified byte array starting at offset off to the underlying output stream. - */ + /// Writes len bytes from the specified byte array starting at offset off to the underlying output stream. public void write(byte[] b, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes the specified byte (the low eight bits of the argument b) to the underlying output stream. - * Implements the write method of OutputStream. - */ + /// Writes the specified byte (the low eight bits of the argument b) to the underlying output stream. + /// Implements the write method of OutputStream. public void write(int b) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a boolean to the underlying output stream as a 1-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0. - */ + /// Writes a boolean to the underlying output stream as a 1-byte value. The value true is written out as the value (byte)1; the value false is written out as the value (byte)0. public final void writeBoolean(boolean v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes out a byte to the underlying output stream as a 1-byte value. - */ + /// Writes out a byte to the underlying output stream as a 1-byte value. public final void writeByte(int v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a char to the underlying output stream as a 2-byte value, high byte first. - */ + /// Writes a char to the underlying output stream as a 2-byte value, high byte first. public final void writeChar(int v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a string to the underlying output stream as a sequence of characters. Each character is written to the data output stream as if by the writeChar method. - */ + /// Writes a string to the underlying output stream as a sequence of characters. Each character is written to the data output stream as if by the writeChar method. public final void writeChars(java.lang.String s) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, high byte first. - */ + /// Converts the double argument to a long using the doubleToLongBits method in class Double, and then writes that long value to the underlying output stream as an 8-byte quantity, high byte first. public final void writeDouble(double v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, high byte first. - */ + /// Converts the float argument to an int using the floatToIntBits method in class Float, and then writes that int value to the underlying output stream as a 4-byte quantity, high byte first. public final void writeFloat(float v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes an int to the underlying output stream as four bytes, high byte first. - */ + /// Writes an int to the underlying output stream as four bytes, high byte first. public final void writeInt(int v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a long to the underlying output stream as eight bytes, high byte first. - */ + /// Writes a long to the underlying output stream as eight bytes, high byte first. public final void writeLong(long v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a short to the underlying output stream as two bytes, high byte first. - */ + /// Writes a short to the underlying output stream as two bytes, high byte first. public final void writeShort(int v) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes a string to the underlying output stream using UTF-8 encoding in a machine-independent manner. - * First, two bytes are written to the output stream as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for the character. - */ + /// Writes a string to the underlying output stream using UTF-8 encoding in a machine-independent manner. + /// First, two bytes are written to the output stream as if by the writeShort method giving the number of bytes to follow. This value is the number of bytes actually written out, not the length of the string. Following the length, each character of the string is output, in sequence, using the UTF-8 encoding for the character. public final void writeUTF(java.lang.String str) throws java.io.IOException{ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/EOFException.java b/Ports/CLDC11/src/java/io/EOFException.java index 04ae6c1ae9..882d923866 100644 --- a/Ports/CLDC11/src/java/io/EOFException.java +++ b/Ports/CLDC11/src/java/io/EOFException.java @@ -22,25 +22,19 @@ * have any questions. */ package java.io; -/** - * Signals that an end of file or end of stream has been reached unexpectedly during input. - * This exception is mainly used by data input streams, which generally expect a binary file in a specific format, and for which an end of stream is an unusual condition. Most other input streams return a special value on end of stream. - * Note that some input operations react to end-of-file by returning a distinguished value (such as -1) rather than by throwing an exception. - * Since: JDK1.0, CLDC 1.0 See Also:DataInputStream, IOException - */ +/// Signals that an end of file or end of stream has been reached unexpectedly during input. +/// This exception is mainly used by data input streams, which generally expect a binary file in a specific format, and for which an end of stream is an unusual condition. Most other input streams return a special value on end of stream. +/// Note that some input operations react to end-of-file by returning a distinguished value (such as -1) rather than by throwing an exception. +/// Since: JDK1.0, CLDC 1.0 See Also:DataInputStream, IOException public class EOFException extends java.io.IOException{ - /** - * Constructs an EOFException with null as its error detail message. - */ + /// Constructs an EOFException with null as its error detail message. public EOFException(){ //TODO codavaj!! } - /** - * Constructs an EOFException with the specified detail message. The string s may later be retrieved by the - * method of class java.lang.Throwable. - * s - the detail message. - */ + /// Constructs an EOFException with the specified detail message. The string s may later be retrieved by the + /// method of class java.lang.Throwable. + /// s - the detail message. public EOFException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/Flushable.java b/Ports/CLDC11/src/java/io/Flushable.java index e0b7c02d0c..0eeea163bf 100644 --- a/Ports/CLDC11/src/java/io/Flushable.java +++ b/Ports/CLDC11/src/java/io/Flushable.java @@ -18,22 +18,17 @@ import java.io.IOException; -/** - *

- * Indicates that an output object can be flushed. - *

- * - * @since 1.5 - */ +/// Indicates that an output object can be flushed. +/// +/// #### Since +/// +/// 1.5 public interface Flushable { - /** - *

- * Flushes the object by writing out any buffered data to the underlying - * output. - *

- * - * @throws IOException - * if there are any issues writing the data. - */ + /// Flushes the object by writing out any buffered data to the underlying + /// output. + /// + /// #### Throws + /// + /// - `IOException`: if there are any issues writing the data. void flush() throws IOException; } diff --git a/Ports/CLDC11/src/java/io/IOException.java b/Ports/CLDC11/src/java/io/IOException.java index 68ccaf2839..95b86405a8 100644 --- a/Ports/CLDC11/src/java/io/IOException.java +++ b/Ports/CLDC11/src/java/io/IOException.java @@ -22,41 +22,34 @@ * have any questions. */ package java.io; -/** - * Signals that an I/O exception of some sort has occurred. This class is the general class of exceptions produced by failed or interrupted I/O operations. - * Since: JDK1.0, CLDC 1.0 See Also:InputStream, OutputStream - */ +/// Signals that an I/O exception of some sort has occurred. This class is the general class of exceptions produced by failed or interrupted I/O operations. +/// Since: JDK1.0, CLDC 1.0 See Also:InputStream, OutputStream public class IOException extends java.lang.Exception{ - /** - * Constructs an IOException with null as its error detail message. - */ + /// Constructs an IOException with null as its error detail message. public IOException(){ //TODO codavaj!! } - /** - * Constructs an IOException with the specified detail message. The error message string s can later be retrieved by the - * method of class java.lang.Throwable. - * s - the detail message. - */ + /// Constructs an IOException with the specified detail message. The error message string s can later be retrieved by the + /// method of class java.lang.Throwable. + /// s - the detail message. public IOException(java.lang.String s){ //TODO codavaj!! } - /** - * Constructs an IOException with the specified cause. - * @param cause - */ + /// Constructs an IOException with the specified cause. + /// + /// #### Parameters + /// + /// - `cause` public IOException(Throwable cause) { //TODO codavaj!! } - /** - * Constructs an IOException with the specified detail message and cause. The error message string s can later be retrieved by the - * method of class java.lang.Throwable. - * s - the detail message. - * cause - The cause. - */ + /// Constructs an IOException with the specified detail message and cause. The error message string s can later be retrieved by the + /// method of class java.lang.Throwable. + /// s - the detail message. + /// cause - The cause. public IOException(java.lang.String s, Throwable cause) { //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/InputStream.java b/Ports/CLDC11/src/java/io/InputStream.java index 3aac441528..5bb26786fe 100644 --- a/Ports/CLDC11/src/java/io/InputStream.java +++ b/Ports/CLDC11/src/java/io/InputStream.java @@ -22,96 +22,76 @@ * have any questions. */ package java.io; -/** - * This abstract class is the superclass of all classes representing an input stream of bytes. - * Applications that need to define a subclass of InputStream must always provide a method that returns the next byte of input. - * Since: JDK1.0, CLDC 1.0 See Also:ByteArrayInputStream, DataInputStream, read(), OutputStream - */ +/// This abstract class is the superclass of all classes representing an input stream of bytes. +/// Applications that need to define a subclass of InputStream must always provide a method that returns the next byte of input. +/// Since: JDK1.0, CLDC 1.0 See Also:ByteArrayInputStream, DataInputStream, read(), OutputStream public abstract class InputStream implements AutoCloseable { public InputStream(){ //TODO codavaj!! } - /** - * Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream. The next caller might be the same thread or another thread. - * The available method for class InputStream always returns 0. - * This method should be overridden by subclasses. - */ + /// Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream. The next caller might be the same thread or another thread. + /// The available method for class InputStream always returns 0. + /// This method should be overridden by subclasses. public int available() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Closes this input stream and releases any system resources associated with the stream. - * The close method of InputStream does nothing. - */ + /// Closes this input stream and releases any system resources associated with the stream. + /// The close method of InputStream does nothing. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. - * The readlimit arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated. - * The general contract of mark is that, if the method markSupported returns true, the stream somehow remembers all the bytes read after the call to mark and stands ready to supply those same bytes again if and whenever the method reset is called. However, the stream is not required to remember any data at all if more than readlimit bytes are read from the stream before reset is called. - * The mark method of InputStream does nothing. - */ + /// Marks the current position in this input stream. A subsequent call to the reset method repositions this stream at the last marked position so that subsequent reads re-read the same bytes. + /// The readlimit arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated. + /// The general contract of mark is that, if the method markSupported returns true, the stream somehow remembers all the bytes read after the call to mark and stands ready to supply those same bytes again if and whenever the method reset is called. However, the stream is not required to remember any data at all if more than readlimit bytes are read from the stream before reset is called. + /// The mark method of InputStream does nothing. public void mark(int readlimit){ return; //TODO codavaj!! } - /** - * Tests if this input stream supports the mark and reset methods. The markSupported method of InputStream returns false. - */ + /// Tests if this input stream supports the mark and reset methods. The markSupported method of InputStream returns false. public boolean markSupported(){ return false; //TODO codavaj!! } - /** - * Reads the next byte of data from the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown. - * A subclass must provide an implementation of this method. - */ + /// Reads the next byte of data from the input stream. The value byte is returned as an int in the range 0 to 255. If no byte is available because the end of the stream has been reached, the value -1 is returned. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown. + /// A subclass must provide an implementation of this method. public abstract int read() throws java.io.IOException; - /** - * Reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown. - * If b is null, a NullPointerException is thrown. If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b. - * The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is, at most, equal to the length of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1], leaving elements b[k] through b[b.length-1] unaffected. - * If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed. - * The read(b) method for class InputStream has the same effect as: read(b, 0, b.length) - */ + /// Reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown. + /// If b is null, a NullPointerException is thrown. If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b. + /// The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is, at most, equal to the length of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1], leaving elements b[k] through b[b.length-1] unaffected. + /// If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed. + /// The read(b) method for class InputStream has the same effect as: read(b, 0, b.length) public int read(byte[] b) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Reads up to len bytes of data from the input stream into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer. - * This method blocks until input data is available, end of file is detected, or an exception is thrown. - * If b is null, a NullPointerException is thrown. - * If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. - * If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b. - * The first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[off+k] through b[off+len-1] unaffected. - * In every case, elements b[0] through b[off] and elements b[off+len] through b[b.length-1] are unaffected. - * If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed. - * The read(b, off, len) method for class InputStream simply calls the method read() repeatedly. If the first such call results in an IOException, that exception is returned from the call to the read(b, off, len) method. If any subsequent call to read() results in a IOException, the exception is caught and treated as if it were end of file; the bytes read up to that point are stored into b and the number of bytes read before the exception occurred is returned. Subclasses are encouraged to provide a more efficient implementation of this method. - */ + /// Reads up to len bytes of data from the input stream into an array of bytes. An attempt is made to read as many as len bytes, but a smaller number may be read, possibly zero. The number of bytes actually read is returned as an integer. + /// This method blocks until input data is available, end of file is detected, or an exception is thrown. + /// If b is null, a NullPointerException is thrown. + /// If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. + /// If len is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b. + /// The first byte read is stored into element b[off], the next one into b[off+1], and so on. The number of bytes read is, at most, equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1], leaving elements b[off+k] through b[off+len-1] unaffected. + /// In every case, elements b[0] through b[off] and elements b[off+len] through b[b.length-1] are unaffected. + /// If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed. + /// The read(b, off, len) method for class InputStream simply calls the method read() repeatedly. If the first such call results in an IOException, that exception is returned from the call to the read(b, off, len) method. If any subsequent call to read() results in a IOException, the exception is caught and treated as if it were end of file; the bytes read up to that point are stored into b and the number of bytes read before the exception occurred is returned. Subclasses are encouraged to provide a more efficient implementation of this method. public int read(byte[] b, int off, int len) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Repositions this stream to the position at the time the mark method was last called on this input stream. - * The general contract of reset is: - * If the method markSupported returns true, then: If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown. If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset. If the method markSupported returns false, then: The call to reset may throw an IOException. If an IOException is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the read method depend on the particular type of the input stream. - * The method reset for class InputStream does nothing and always throws an IOException. - */ + /// Repositions this stream to the position at the time the mark method was last called on this input stream. + /// The general contract of reset is: + /// If the method markSupported returns true, then: If the method mark has not been called since the stream was created, or the number of bytes read from the stream since mark was last called is larger than the argument to mark at that last call, then an IOException might be thrown. If such an IOException is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to mark (or since the start of the file, if mark has not been called) will be resupplied to subsequent callers of the read method, followed by any bytes that otherwise would have been the next input data as of the time of the call to reset. If the method markSupported returns false, then: The call to reset may throw an IOException. If an IOException is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the read method depend on the particular type of the input stream. + /// The method reset for class InputStream does nothing and always throws an IOException. public void reset() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped. - * The skip method of InputStream creates a byte array and then repeatedly reads into it until n bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method. - */ + /// Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped. + /// The skip method of InputStream creates a byte array and then repeatedly reads into it until n bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method. public long skip(long n) throws java.io.IOException{ return 0l; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/InputStreamReader.java b/Ports/CLDC11/src/java/io/InputStreamReader.java index 38f798beb4..9769621f7b 100644 --- a/Ports/CLDC11/src/java/io/InputStreamReader.java +++ b/Ports/CLDC11/src/java/io/InputStreamReader.java @@ -22,81 +22,59 @@ * have any questions. */ package java.io; -/** - * An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and translates them into characters. The encoding that it uses may be specified by name, or the platform's default encoding may be accepted. - * Each invocation of one of an InputStreamReader's read() methods may cause one or more bytes to be read from the underlying byte input stream. To enable the efficient conversion of bytes to characters, more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation. - * Since: CLDC 1.0 See Also:Reader, UnsupportedEncodingException - */ +/// An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and translates them into characters. The encoding that it uses may be specified by name, or the platform's default encoding may be accepted. +/// Each invocation of one of an InputStreamReader's read() methods may cause one or more bytes to be read from the underlying byte input stream. To enable the efficient conversion of bytes to characters, more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation. +/// Since: CLDC 1.0 See Also:Reader, UnsupportedEncodingException public class InputStreamReader extends java.io.Reader{ - /** - * Create an InputStreamReader that uses the default character encoding. - * is - An InputStream - */ + /// Create an InputStreamReader that uses the default character encoding. + /// is - An InputStream public InputStreamReader(java.io.InputStream is){ //TODO codavaj!! } - /** - * Create an InputStreamReader that uses the named character encoding. - * is - An InputStreamenc - The name of a supported character encoding - * - If the named encoding is not supported - */ + /// Create an InputStreamReader that uses the named character encoding. + /// is - An InputStreamenc - The name of a supported character encoding + /// - If the named encoding is not supported public InputStreamReader(java.io.InputStream is, java.lang.String enc) throws java.io.UnsupportedEncodingException{ //TODO codavaj!! } - /** - * Close the stream. Closing a previously closed stream has no effect. - */ + /// Close the stream. Closing a previously closed stream has no effect. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Mark the present position in the stream. - */ + /// Mark the present position in the stream. public void mark(int readAheadLimit) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Tell whether this stream supports the mark() operation. - */ + /// Tell whether this stream supports the mark() operation. public boolean markSupported(){ return false; //TODO codavaj!! } - /** - * Read a single character. - */ + /// Read a single character. public int read() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Read characters into a portion of an array. - */ + /// Read characters into a portion of an array. public int read(char[] cbuf, int off, int len) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Tell whether this stream is ready to be read. - */ + /// Tell whether this stream is ready to be read. public boolean ready() throws java.io.IOException{ return false; //TODO codavaj!! } - /** - * Reset the stream. - */ + /// Reset the stream. public void reset() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Skip characters. - */ + /// Skip characters. public long skip(long n) throws java.io.IOException{ return 0l; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/InterruptedIOException.java b/Ports/CLDC11/src/java/io/InterruptedIOException.java index 835c499532..13be9c939b 100644 --- a/Ports/CLDC11/src/java/io/InterruptedIOException.java +++ b/Ports/CLDC11/src/java/io/InterruptedIOException.java @@ -22,28 +22,20 @@ * have any questions. */ package java.io; -/** - * Signals that an I/O operation has been interrupted. An InterruptedIOException is thrown to indicate that an input or output transfer has been terminated because the thread performing it was terminated. The field bytesTransferred indicates how many bytes were successfully transferred before the interruption occurred. - * Since: JDK1.0, CLDC 1.0 See Also:InputStream, OutputStream - */ +/// Signals that an I/O operation has been interrupted. An InterruptedIOException is thrown to indicate that an input or output transfer has been terminated because the thread performing it was terminated. The field bytesTransferred indicates how many bytes were successfully transferred before the interruption occurred. +/// Since: JDK1.0, CLDC 1.0 See Also:InputStream, OutputStream public class InterruptedIOException extends java.io.IOException{ - /** - * Reports how many bytes had been transferred as part of the I/O operation before it was interrupted. - */ + /// Reports how many bytes had been transferred as part of the I/O operation before it was interrupted. public int bytesTransferred; - /** - * Constructs an InterruptedIOException with null as its error detail message. - */ + /// Constructs an InterruptedIOException with null as its error detail message. public InterruptedIOException(){ //TODO codavaj!! } - /** - * Constructs an InterruptedIOException with the specified detail message. The string s can be retrieved later by the - * method of class java.lang.Throwable. - * s - the detail message. - */ + /// Constructs an InterruptedIOException with the specified detail message. The string s can be retrieved later by the + /// method of class java.lang.Throwable. + /// s - the detail message. public InterruptedIOException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/OutputStream.java b/Ports/CLDC11/src/java/io/OutputStream.java index 49398a8cd1..ee54f5a6a4 100644 --- a/Ports/CLDC11/src/java/io/OutputStream.java +++ b/Ports/CLDC11/src/java/io/OutputStream.java @@ -22,53 +22,41 @@ * have any questions. */ package java.io; -/** - * This abstract class is the superclass of all classes representing an output stream of bytes. An output stream accepts output bytes and sends them to some sink. - * Applications that need to define a subclass of OutputStream must always provide at least a method that writes one byte of output. - * Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, DataOutputStream, InputStream, write(int) - */ +/// This abstract class is the superclass of all classes representing an output stream of bytes. An output stream accepts output bytes and sends them to some sink. +/// Applications that need to define a subclass of OutputStream must always provide at least a method that writes one byte of output. +/// Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, DataOutputStream, InputStream, write(int) public abstract class OutputStream implements AutoCloseable { public OutputStream(){ //TODO codavaj!! } - /** - * Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened. - * The close method of OutputStream does nothing. - */ + /// Closes this output stream and releases any system resources associated with this stream. The general contract of close is that it closes the output stream. A closed stream cannot perform output operations and cannot be reopened. + /// The close method of OutputStream does nothing. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Flushes this output stream and forces any buffered output bytes to be written out. The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination. - * The flush method of OutputStream does nothing. - */ + /// Flushes this output stream and forces any buffered output bytes to be written out. The general contract of flush is that calling it is an indication that, if any bytes previously written have been buffered by the implementation of the output stream, such bytes should immediately be written to their intended destination. + /// The flush method of OutputStream does nothing. public void flush() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length). - */ + /// Writes b.length bytes from the specified byte array to this output stream. The general contract for write(b) is that it should have exactly the same effect as the call write(b, 0, b.length). public void write(byte[] b) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation. - * The write method of OutputStream calls the write method of one argument on each of the bytes to be written out. Subclasses are encouraged to override this method and provide a more efficient implementation. - * If b is null, a NullPointerException is thrown. - * If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. - */ + /// Writes len bytes from the specified byte array starting at offset off to this output stream. The general contract for write(b, off, len) is that some of the bytes in the array b are written to the output stream in order; element b[off] is the first byte written and b[off+len-1] is the last byte written by this operation. + /// The write method of OutputStream calls the write method of one argument on each of the bytes to be written out. Subclasses are encouraged to override this method and provide a more efficient implementation. + /// If b is null, a NullPointerException is thrown. + /// If off is negative, or len is negative, or off+len is greater than the length of the array b, then an IndexOutOfBoundsException is thrown. public void write(byte[] b, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored. - * Subclasses of OutputStream must provide an implementation for this method. - */ + /// Writes the specified byte to this output stream. The general contract for write is that one byte is written to the output stream. The byte to be written is the eight low-order bits of the argument b. The 24 high-order bits of b are ignored. + /// Subclasses of OutputStream must provide an implementation for this method. public abstract void write(int b) throws java.io.IOException; } diff --git a/Ports/CLDC11/src/java/io/OutputStreamWriter.java b/Ports/CLDC11/src/java/io/OutputStreamWriter.java index 081cd3d9a5..4e666f37c0 100644 --- a/Ports/CLDC11/src/java/io/OutputStreamWriter.java +++ b/Ports/CLDC11/src/java/io/OutputStreamWriter.java @@ -22,60 +22,44 @@ * have any questions. */ package java.io; -/** - * An OutputStreamWriter is a bridge from character streams to byte streams: Characters written to it are translated into bytes. The encoding that it uses may be specified by name, or the platform's default encoding may be accepted. - * Each invocation of a write() method causes the encoding converter to be invoked on the given character(s). The resulting bytes are accumulated in a buffer before being written to the underlying output stream. The size of this buffer may be specified, but by default it is large enough for most purposes. Note that the characters passed to the write() methods are not buffered. - * Since: CLDC 1.0 See Also:Writer, UnsupportedEncodingException - */ +/// An OutputStreamWriter is a bridge from character streams to byte streams: Characters written to it are translated into bytes. The encoding that it uses may be specified by name, or the platform's default encoding may be accepted. +/// Each invocation of a write() method causes the encoding converter to be invoked on the given character(s). The resulting bytes are accumulated in a buffer before being written to the underlying output stream. The size of this buffer may be specified, but by default it is large enough for most purposes. Note that the characters passed to the write() methods are not buffered. +/// Since: CLDC 1.0 See Also:Writer, UnsupportedEncodingException public class OutputStreamWriter extends java.io.Writer{ - /** - * Create an OutputStreamWriter that uses the default character encoding. - * os - An OutputStream - */ + /// Create an OutputStreamWriter that uses the default character encoding. + /// os - An OutputStream public OutputStreamWriter(java.io.OutputStream os){ //TODO codavaj!! } - /** - * Create an OutputStreamWriter that uses the named character encoding. - * os - An OutputStreamenc - The name of a supported - * - If the named encoding is not supported - */ + /// Create an OutputStreamWriter that uses the named character encoding. + /// os - An OutputStreamenc - The name of a supported + /// - If the named encoding is not supported public OutputStreamWriter(java.io.OutputStream os, java.lang.String enc) throws java.io.UnsupportedEncodingException{ //TODO codavaj!! } - /** - * Close the stream. - */ + /// Close the stream. public void close() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Flush the stream. - */ + /// Flush the stream. public void flush() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a portion of an array of characters. - */ + /// Write a portion of an array of characters. public void write(char[] cbuf, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a single character. - */ + /// Write a single character. public void write(int c) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a portion of a string. - */ + /// Write a portion of a string. public void write(java.lang.String str, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/PrintStream.java b/Ports/CLDC11/src/java/io/PrintStream.java index 41f6a38617..105577e089 100644 --- a/Ports/CLDC11/src/java/io/PrintStream.java +++ b/Ports/CLDC11/src/java/io/PrintStream.java @@ -22,54 +22,40 @@ * have any questions. */ package java.io; -/** - * A PrintStream adds functionality to another output stream, namely the ability to print representations of various data values conveniently. Two other features are provided as well. Unlike other output streams, a PrintStream never throws an IOException; instead, exceptional situations merely set an internal flag that can be tested via the checkError method. - * All characters printed by a PrintStream are converted into bytes using the platform's default character encoding. - * Since: JDK1.0, CLDC 1.0 - */ +/// A PrintStream adds functionality to another output stream, namely the ability to print representations of various data values conveniently. Two other features are provided as well. Unlike other output streams, a PrintStream never throws an IOException; instead, exceptional situations merely set an internal flag that can be tested via the checkError method. +/// All characters printed by a PrintStream are converted into bytes using the platform's default character encoding. +/// Since: JDK1.0, CLDC 1.0 public class PrintStream extends java.io.OutputStream{ - /** - * Create a new print stream. This stream will not flush automatically. - * out - The output stream to which values and objects will be printed - */ + /// Create a new print stream. This stream will not flush automatically. + /// out - The output stream to which values and objects will be printed public PrintStream(java.io.OutputStream out){ //TODO codavaj!! } - /** - * Flush the stream and check its error state. The internal error state is set to true when the underlying output stream throws an IOException, and when the setError method is invoked. - */ + /// Flush the stream and check its error state. The internal error state is set to true when the underlying output stream throws an IOException, and when the setError method is invoked. public boolean checkError(){ return false; //TODO codavaj!! } - /** - * Close the stream. This is done by flushing the stream and then closing the underlying output stream. - */ + /// Close the stream. This is done by flushing the stream and then closing the underlying output stream. public void close(){ return; //TODO codavaj!! } - /** - * Flush the stream. This is done by writing any buffered output bytes to the underlying output stream and then flushing that stream. - */ + /// Flush the stream. This is done by writing any buffered output bytes to the underlying output stream and then flushing that stream. public void flush(){ return; //TODO codavaj!! } - /** - * Print a boolean value. The string produced by - * is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print a boolean value. The string produced by + /// is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(boolean b){ return; //TODO codavaj!! } - /** - * Print an array of characters. The characters are converted into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print an array of characters. The characters are converted into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(char c){ return; //TODO codavaj!! } @@ -78,80 +64,62 @@ void print(char[] s){ return; //TODO codavaj!! } - /** - * Print a double-precision floating point number. The string produced by - * is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print a double-precision floating point number. The string produced by + /// is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(double d){ return; //TODO codavaj!! } - /** - * Print a floating point number. The string produced by - * is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print a floating point number. The string produced by + /// is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(float f){ return; //TODO codavaj!! } - /** - * Print an integer. The string produced by - * is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print an integer. The string produced by + /// is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(int i){ return; //TODO codavaj!! } - /** - * Print a long integer. The string produced by - * is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print a long integer. The string produced by + /// is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(long l){ return; //TODO codavaj!! } - /** - * Print an object. The string produced by the - * method is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print an object. The string produced by the + /// method is translated into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(java.lang.Object obj){ return; //TODO codavaj!! } - /** - * Print a string. If the argument is null then the string "null" is printed. Otherwise, the string's characters are converted into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the - * method. - */ + /// Print a string. If the argument is null then the string "null" is printed. Otherwise, the string's characters are converted into bytes according to the platform's default character encoding, and these bytes are written in exactly the manner of the + /// method. public void print(java.lang.String s){ return; //TODO codavaj!! } - /** - * Terminate the current line by writing the line separator string. The line separator string is defined by the system property line.separator, and is not necessarily a single newline character ('\n'). - */ + /// Terminate the current line by writing the line separator string. The line separator string is defined by the system property line.separator, and is not necessarily a single newline character ('\n'). public void println(){ return; //TODO codavaj!! } - /** - * Print a boolean and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print a boolean and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(boolean x){ return; //TODO codavaj!! } - /** - * Print an array of characters and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print an array of characters and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(char x){ return; //TODO codavaj!! } @@ -160,79 +128,61 @@ void println(char[] x){ return; //TODO codavaj!! } - /** - * Print a double and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print a double and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(double x){ return; //TODO codavaj!! } - /** - * Print a float and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print a float and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(float x){ return; //TODO codavaj!! } - /** - * Print an integer and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print an integer and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(int x){ return; //TODO codavaj!! } - /** - * Print a long and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print a long and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(long x){ return; //TODO codavaj!! } - /** - * Print an Object and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print an Object and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(java.lang.Object x){ return; //TODO codavaj!! } - /** - * Print a String and then terminate the line. This method behaves as though it invokes - * and then - * . - */ + /// Print a String and then terminate the line. This method behaves as though it invokes + /// and then + /// . public void println(java.lang.String x){ return; //TODO codavaj!! } - /** - * Set the error state of the stream to true. - */ + /// Set the error state of the stream to true. protected void setError(){ return; //TODO codavaj!! } - /** - * Write len bytes from the specified byte array starting at offset off to this stream. - * Note that the bytes will be written as given; to write characters that will be translated according to the platform's default character encoding, use the print(char) or println(char) methods. - */ + /// Write len bytes from the specified byte array starting at offset off to this stream. + /// Note that the bytes will be written as given; to write characters that will be translated according to the platform's default character encoding, use the print(char) or println(char) methods. public void write(byte[] buf, int off, int len){ return; //TODO codavaj!! } - /** - * Write the specified byte to this stream. - * Note that the byte is written as given; to write a character that will be translated according to the platform's default character encoding, use the print(char) or println(char) methods. - */ + /// Write the specified byte to this stream. + /// Note that the byte is written as given; to write a character that will be translated according to the platform's default character encoding, use the print(char) or println(char) methods. public void write(int b){ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/Reader.java b/Ports/CLDC11/src/java/io/Reader.java index c7ed91790d..094f8088ab 100644 --- a/Ports/CLDC11/src/java/io/Reader.java +++ b/Ports/CLDC11/src/java/io/Reader.java @@ -22,87 +22,61 @@ * have any questions. */ package java.io; -/** - * Abstract class for reading character streams. The only methods that a subclass must implement are read(char[], int, int) and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both. - * Since: JDK1.1, CLDC 1.0 See Also:InputStreamReader, Writer - */ +/// Abstract class for reading character streams. The only methods that a subclass must implement are read(char[], int, int) and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both. +/// Since: JDK1.1, CLDC 1.0 See Also:InputStreamReader, Writer public abstract class Reader implements AutoCloseable { - /** - * The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method. - */ + /// The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method. protected java.lang.Object lock; - /** - * Create a new character-stream reader whose critical sections will synchronize on the reader itself. - */ + /// Create a new character-stream reader whose critical sections will synchronize on the reader itself. protected Reader(){ //TODO codavaj!! } - /** - * Create a new character-stream reader whose critical sections will synchronize on the given object. - * lock - The Object to synchronize on. - */ + /// Create a new character-stream reader whose critical sections will synchronize on the given object. + /// lock - The Object to synchronize on. protected Reader(java.lang.Object lock){ //TODO codavaj!! } - /** - * Close the stream. Once a stream has been closed, further read(), ready(), mark(), or reset() invocations will throw an IOException. Closing a previously-closed stream, however, has no effect. - */ + /// Close the stream. Once a stream has been closed, further read(), ready(), mark(), or reset() invocations will throw an IOException. Closing a previously-closed stream, however, has no effect. public abstract void close() throws java.io.IOException; - /** - * Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point. Not all character-input streams support the mark() operation. - */ + /// Mark the present position in the stream. Subsequent calls to reset() will attempt to reposition the stream to this point. Not all character-input streams support the mark() operation. public void mark(int readAheadLimit) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Tell whether this stream supports the mark() operation. The default implementation always returns false. Subclasses should override this method. - */ + /// Tell whether this stream supports the mark() operation. The default implementation always returns false. Subclasses should override this method. public boolean markSupported(){ return false; //TODO codavaj!! } - /** - * Read a single character. This method will block until a character is available, an I/O error occurs, or the end of the stream is reached. - * Subclasses that intend to support efficient single-character input should override this method. - */ + /// Read a single character. This method will block until a character is available, an I/O error occurs, or the end of the stream is reached. + /// Subclasses that intend to support efficient single-character input should override this method. public int read() throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Read characters into an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached. - */ + /// Read characters into an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached. public int read(char[] cbuf) throws java.io.IOException{ return 0; //TODO codavaj!! } - /** - * Read characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached. - */ + /// Read characters into a portion of an array. This method will block until some input is available, an I/O error occurs, or the end of the stream is reached. public abstract int read(char[] cbuf, int off, int len) throws java.io.IOException; - /** - * Tell whether this stream is ready to be read. - */ + /// Tell whether this stream is ready to be read. public boolean ready() throws java.io.IOException{ return false; //TODO codavaj!! } - /** - * Reset the stream. If the stream has been marked, then attempt to reposition it at the mark. If the stream has not been marked, then attempt to reset it in some way appropriate to the particular stream, for example by repositioning it to its starting point. Not all character-input streams support the reset() operation, and some support reset() without supporting mark(). - */ + /// Reset the stream. If the stream has been marked, then attempt to reposition it at the mark. If the stream has not been marked, then attempt to reset it in some way appropriate to the particular stream, for example by repositioning it to its starting point. Not all character-input streams support the reset() operation, and some support reset() without supporting mark(). public void reset() throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Skip characters. This method will block until some characters are available, an I/O error occurs, or the end of the stream is reached. - */ + /// Skip characters. This method will block until some characters are available, an I/O error occurs, or the end of the stream is reached. public long skip(long n) throws java.io.IOException{ return 0l; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/Serializable.java b/Ports/CLDC11/src/java/io/Serializable.java index 05f3a0ca7a..f6a3bc543f 100644 --- a/Ports/CLDC11/src/java/io/Serializable.java +++ b/Ports/CLDC11/src/java/io/Serializable.java @@ -23,11 +23,9 @@ */ package java.io; -/** - * Here to simplify porting, won't actually work... - * - * @author Shai Almog - */ +/// Here to simplify porting, won't actually work... +/// +/// @author Shai Almog public interface Serializable { } diff --git a/Ports/CLDC11/src/java/io/StringReader.java b/Ports/CLDC11/src/java/io/StringReader.java index 9062e7703b..77deeb75e4 100644 --- a/Ports/CLDC11/src/java/io/StringReader.java +++ b/Ports/CLDC11/src/java/io/StringReader.java @@ -17,12 +17,12 @@ package java.io; -/** - * A specialized {@link Reader} that reads characters from a {@code String} in - * a sequential manner. - * - * @see StringWriter - */ +/// A specialized `Reader` that reads characters from a `String` in +/// a sequential manner. +/// +/// #### See also +/// +/// - StringWriter public class StringReader extends Reader { private String str; @@ -32,53 +32,55 @@ public class StringReader extends Reader { private int count; - /** - * Construct a new {@code StringReader} with {@code str} as source. The size - * of the reader is set to the {@code length()} of the string and the Object - * to synchronize access through is set to {@code str}. - * - * @param str - * the source string for this reader. - */ + /// Construct a new `StringReader` with `str` as source. The size + /// of the reader is set to the `length()` of the string and the Object + /// to synchronize access through is set to `str`. + /// + /// #### Parameters + /// + /// - `str`: the source string for this reader. public StringReader(String str) { super(); this.str = str; this.count = str.length(); } - /** - * Closes this reader. Once it is closed, read operations on this reader - * will throw an {@code IOException}. Only the first invocation of this - * method has any effect. - */ + /// Closes this reader. Once it is closed, read operations on this reader + /// will throw an `IOException`. Only the first invocation of this + /// method has any effect. @Override public void close() { str = null; } - /** - * Returns a boolean indicating whether this reader is closed. - * - * @return {@code true} if closed, otherwise {@code false}. - */ + /// Returns a boolean indicating whether this reader is closed. + /// + /// #### Returns + /// + /// `true` if closed, otherwise `false`. private boolean isClosed() { return str == null; } - /** - * Sets a mark position in this reader. The parameter {@code readLimit} is - * ignored for this class. Calling {@code reset()} will reposition the - * reader back to the marked position. - * - * @param readLimit - * ignored for {@code StringReader} instances. - * @throws IllegalArgumentException - * if {@code readLimit < 0}. - * @throws IOException - * if this reader is closed. - * @see #markSupported() - * @see #reset() - */ + /// Sets a mark position in this reader. The parameter `readLimit` is + /// ignored for this class. Calling `reset()` will reposition the + /// reader back to the marked position. + /// + /// #### Parameters + /// + /// - `readLimit`: ignored for `StringReader` instances. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `readLimit < 0`. + /// + /// - `IOException`: if this reader is closed. + /// + /// #### See also + /// + /// - #markSupported() + /// + /// - #reset() @Override public void mark(int readLimit) throws IOException { if (readLimit < 0) { @@ -93,27 +95,28 @@ public void mark(int readLimit) throws IOException { } } - /** - * Indicates whether this reader supports the {@code mark()} and {@code - * reset()} methods. This implementation returns {@code true}. - * - * @return always {@code true}. - */ + /// Indicates whether this reader supports the `mark()` and `reset()` methods. This implementation returns `true`. + /// + /// #### Returns + /// + /// always `true`. @Override public boolean markSupported() { return true; } - /** - * Reads a single character from the source string and returns it as an - * integer with the two higher-order bytes set to 0. Returns -1 if the end - * of the source string has been reached. - * - * @return the character read or -1 if the end of the source string has been - * reached. - * @throws IOException - * if this reader is closed. - */ + /// Reads a single character from the source string and returns it as an + /// integer with the two higher-order bytes set to 0. Returns -1 if the end + /// of the source string has been reached. + /// + /// #### Returns + /// + /// @return the character read or -1 if the end of the source string has been + /// reached. + /// + /// #### Throws + /// + /// - `IOException`: if this reader is closed. @Override public int read() throws IOException { synchronized (lock) { @@ -127,27 +130,33 @@ public int read() throws IOException { } } - /** - * Reads at most {@code len} characters from the source string and stores - * them at {@code offset} in the character array {@code buf}. Returns the - * number of characters actually read or -1 if the end of the source string - * has been reached. - * - * @param buf - * the character array to store the characters read. - * @param offset - * the initial position in {@code buffer} to store the characters - * read from this reader. - * @param len - * the maximum number of characters to read. - * @return the number of characters read or -1 if the end of the reader has - * been reached. - * @throws IndexOutOfBoundsException - * if {@code offset < 0} or {@code len < 0}, or if - * {@code offset + len} is greater than the size of {@code buf}. - * @throws IOException - * if this reader is closed. - */ + /// Reads at most `len` characters from the source string and stores + /// them at `offset` in the character array `buf`. Returns the + /// number of characters actually read or -1 if the end of the source string + /// has been reached. + /// + /// #### Parameters + /// + /// - `buf`: the character array to store the characters read. + /// + /// - `offset`: @param offset + /// the initial position in `buffer` to store the characters + /// read from this reader. + /// + /// - `len`: the maximum number of characters to read. + /// + /// #### Returns + /// + /// @return the number of characters read or -1 if the end of the reader has + /// been reached. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `offset < 0` or `len < 0`, or if + /// `offset + len` is greater than the size of `buf`. + /// + /// - `IOException`: if this reader is closed. @Override public int read(char buf[], int offset, int len) throws IOException { synchronized (lock) { @@ -177,16 +186,22 @@ public int read(char buf[], int offset, int len) throws IOException { } } - /** - * Indicates whether this reader is ready to be read without blocking. This - * implementation always returns {@code true}. - * - * @return always {@code true}. - * @throws IOException - * if this reader is closed. - * @see #read() - * @see #read(char[], int, int) - */ + /// Indicates whether this reader is ready to be read without blocking. This + /// implementation always returns `true`. + /// + /// #### Returns + /// + /// always `true`. + /// + /// #### Throws + /// + /// - `IOException`: if this reader is closed. + /// + /// #### See also + /// + /// - #read() + /// + /// - #read(char[], int, int) @Override public boolean ready() throws IOException { synchronized (lock) { @@ -197,17 +212,20 @@ public boolean ready() throws IOException { } } - /** - * Resets this reader's position to the last {@code mark()} location. - * Invocations of {@code read()} and {@code skip()} will occur from this new - * location. If this reader has not been marked, it is reset to the - * beginning of the source string. - * - * @throws IOException - * if this reader is closed. - * @see #mark(int) - * @see #markSupported() - */ + /// Resets this reader's position to the last `mark()` location. + /// Invocations of `read()` and `skip()` will occur from this new + /// location. If this reader has not been marked, it is reset to the + /// beginning of the source string. + /// + /// #### Throws + /// + /// - `IOException`: if this reader is closed. + /// + /// #### See also + /// + /// - #mark(int) + /// + /// - #markSupported() @Override public void reset() throws IOException { synchronized (lock) { @@ -218,26 +236,36 @@ public void reset() throws IOException { } } - /** - * Moves {@code ns} characters in the source string. Unlike the {@link - * Reader#skip(long) overridden method}, this method may skip negative skip - * distances: this rewinds the input so that characters may be read again. - * When the end of the source string has been reached, the input cannot be - * rewound. - * - * @param ns - * the maximum number of characters to skip. Positive values skip - * forward; negative values skip backward. - * @return the number of characters actually skipped. This is bounded below - * by the number of characters already read and above by the - * number of characters remaining:
{@code -(num chars already - * read) <= distance skipped <= num chars remaining}. - * @throws IOException - * if this reader is closed. - * @see #mark(int) - * @see #markSupported() - * @see #reset() - */ + /// Moves `ns` characters in the source string. Unlike the `overridden method`, this method may skip negative skip + /// distances: this rewinds the input so that characters may be read again. + /// When the end of the source string has been reached, the input cannot be + /// rewound. + /// + /// #### Parameters + /// + /// - `ns`: @param ns + /// the maximum number of characters to skip. Positive values skip + /// forward; negative values skip backward. + /// + /// #### Returns + /// + /// @return the number of characters actually skipped. This is bounded below + /// by the number of characters already read and above by the + /// number of characters remaining: + /// `-(num chars already + /// read) <= distance skipped <= num chars remaining`. + /// + /// #### Throws + /// + /// - `IOException`: if this reader is closed. + /// + /// #### See also + /// + /// - #mark(int) + /// + /// - #markSupported() + /// + /// - #reset() @Override public long skip(long ns) throws IOException { synchronized (lock) { diff --git a/Ports/CLDC11/src/java/io/StringWriter.java b/Ports/CLDC11/src/java/io/StringWriter.java index ba236ed236..ef98c6769c 100644 --- a/Ports/CLDC11/src/java/io/StringWriter.java +++ b/Ports/CLDC11/src/java/io/StringWriter.java @@ -16,10 +16,7 @@ */ package java.io; -/** - * - * @author shannah - */ +/// @author shannah public class StringWriter extends Writer implements Appendable { private StringBuffer buf; diff --git a/Ports/CLDC11/src/java/io/UTFDataFormatException.java b/Ports/CLDC11/src/java/io/UTFDataFormatException.java index 26bacde691..a7ceaac2f5 100644 --- a/Ports/CLDC11/src/java/io/UTFDataFormatException.java +++ b/Ports/CLDC11/src/java/io/UTFDataFormatException.java @@ -22,23 +22,17 @@ * have any questions. */ package java.io; -/** - * Signals that a malformed UTF-8 string has been read in a data input stream or by any class that implements the data input interface. See the writeUTF method for the format in which UTF-8 strings are read and written. - * Since: JDK1.0, CLDC 1.0 See Also:DataInput, DataInputStream.readUTF(java.io.DataInput), IOException - */ +/// Signals that a malformed UTF-8 string has been read in a data input stream or by any class that implements the data input interface. See the writeUTF method for the format in which UTF-8 strings are read and written. +/// Since: JDK1.0, CLDC 1.0 See Also:DataInput, DataInputStream.readUTF(java.io.DataInput), IOException public class UTFDataFormatException extends java.io.IOException{ - /** - * Constructs a UTFDataFormatException with null as its error detail message. - */ + /// Constructs a UTFDataFormatException with null as its error detail message. public UTFDataFormatException(){ //TODO codavaj!! } - /** - * Constructs a UTFDataFormatException with the specified detail message. The string s can be retrieved later by the - * method of class java.lang.Throwable. - * s - the detail message. - */ + /// Constructs a UTFDataFormatException with the specified detail message. The string s can be retrieved later by the + /// method of class java.lang.Throwable. + /// s - the detail message. public UTFDataFormatException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/UnsupportedEncodingException.java b/Ports/CLDC11/src/java/io/UnsupportedEncodingException.java index 7ae829440e..7e2423b4db 100644 --- a/Ports/CLDC11/src/java/io/UnsupportedEncodingException.java +++ b/Ports/CLDC11/src/java/io/UnsupportedEncodingException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.io; -/** - * The Character Encoding is not supported. - * Since: JDK1.1, CLDC 1.0 - */ +/// The Character Encoding is not supported. +/// Since: JDK1.1, CLDC 1.0 public class UnsupportedEncodingException extends java.io.IOException{ - /** - * Constructs an UnsupportedEncodingException without a detail message. - */ + /// Constructs an UnsupportedEncodingException without a detail message. public UnsupportedEncodingException(){ //TODO codavaj!! } - /** - * Constructs an UnsupportedEncodingException with a detail message. - * s - Describes the reason for the exception. - */ + /// Constructs an UnsupportedEncodingException with a detail message. + /// s - Describes the reason for the exception. public UnsupportedEncodingException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/io/Writer.java b/Ports/CLDC11/src/java/io/Writer.java index 671f95517d..99b31b10fb 100644 --- a/Ports/CLDC11/src/java/io/Writer.java +++ b/Ports/CLDC11/src/java/io/Writer.java @@ -22,71 +22,49 @@ * have any questions. */ package java.io; -/** - * Abstract class for writing to character streams. The only methods that a subclass must implement are write(char[], int, int), flush(), and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both. - * Since: JDK1.1, CLDC 1.0 See Also:OutputStreamWriter, Reader - */ +/// Abstract class for writing to character streams. The only methods that a subclass must implement are write(char[], int, int), flush(), and close(). Most subclasses, however, will override some of the methods defined here in order to provide higher efficiency, additional functionality, or both. +/// Since: JDK1.1, CLDC 1.0 See Also:OutputStreamWriter, Reader public abstract class Writer implements AutoCloseable { - /** - * The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method. - */ + /// The object used to synchronize operations on this stream. For efficiency, a character-stream object may use an object other than itself to protect critical sections. A subclass should therefore use the object in this field rather than this or a synchronized method. protected java.lang.Object lock; - /** - * Create a new character-stream writer whose critical sections will synchronize on the writer itself. - */ + /// Create a new character-stream writer whose critical sections will synchronize on the writer itself. protected Writer(){ //TODO codavaj!! } - /** - * Create a new character-stream writer whose critical sections will synchronize on the given object. - * lock - Object to synchronize on. - */ + /// Create a new character-stream writer whose critical sections will synchronize on the given object. + /// lock - Object to synchronize on. protected Writer(java.lang.Object lock){ //TODO codavaj!! } - /** - * Close the stream, flushing it first. Once a stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously-closed stream, however, has no effect. - */ + /// Close the stream, flushing it first. Once a stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously-closed stream, however, has no effect. public abstract void close() throws java.io.IOException; - /** - * Flush the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams. - */ + /// Flush the stream. If the stream has saved any characters from the various write() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams. public abstract void flush() throws java.io.IOException; - /** - * Write an array of characters. - */ + /// Write an array of characters. public void write(char[] cbuf) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a portion of an array of characters. - */ + /// Write a portion of an array of characters. public abstract void write(char[] cbuf, int off, int len) throws java.io.IOException; - /** - * Write a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored. - * Subclasses that intend to support efficient single-character output should override this method. - */ + /// Write a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored. + /// Subclasses that intend to support efficient single-character output should override this method. public void write(int c) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a string. - */ + /// Write a string. public void write(java.lang.String str) throws java.io.IOException{ return; //TODO codavaj!! } - /** - * Write a portion of a string. - */ + /// Write a portion of a string. public void write(java.lang.String str, int off, int len) throws java.io.IOException{ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/AbstractMethodError.java b/Ports/CLDC11/src/java/lang/AbstractMethodError.java index 0ce0f54462..b8008b8b22 100644 --- a/Ports/CLDC11/src/java/lang/AbstractMethodError.java +++ b/Ports/CLDC11/src/java/lang/AbstractMethodError.java @@ -22,10 +22,8 @@ */ package java.lang; -/** - * Exception thrown when an attempt is made to call an abstract method. - * @author shannah - */ +/// Exception thrown when an attempt is made to call an abstract method. +/// @author shannah public class AbstractMethodError extends Error { AbstractMethodError() { diff --git a/Ports/CLDC11/src/java/lang/Appendable.java b/Ports/CLDC11/src/java/lang/Appendable.java index 55316ec398..34aeaf50c1 100644 --- a/Ports/CLDC11/src/java/lang/Appendable.java +++ b/Ports/CLDC11/src/java/lang/Appendable.java @@ -18,70 +18,83 @@ import java.io.IOException; -/** - * Declares methods to append characters or character sequences. Any class that - * implements this interface can receive data formatted by a - * java.util.Formatter. The appended character or character sequence - * should be valid according to the rules described in - * {@link Character Unicode Character Representation}. - *

- * {@code Appendable} itself does not guarantee thread safety. This - * responsibility is up to the implementing class. - *

- * Implementing classes can choose different exception handling mechanism. They - * can choose to throw exceptions other than {@code IOException} or they do not - * throw any exceptions at all and use error codes instead. - */ +/// Declares methods to append characters or character sequences. Any class that +/// implements this interface can receive data formatted by a +/// `java.util.Formatter`. The appended character or character sequence +/// should be valid according to the rules described in +/// `Unicode Character Representation`. +/// +/// `Appendable` itself does not guarantee thread safety. This +/// responsibility is up to the implementing class. +/// +/// Implementing classes can choose different exception handling mechanism. They +/// can choose to throw exceptions other than `IOException` or they do not +/// throw any exceptions at all and use error codes instead. public interface Appendable { - /** - * Appends the specified character. - * - * @param c - * the character to append. - * @return this {@code Appendable}. - * @throws IOException - * if an I/O error occurs. - */ + /// Appends the specified character. + /// + /// #### Parameters + /// + /// - `c`: the character to append. + /// + /// #### Returns + /// + /// this `Appendable`. + /// + /// #### Throws + /// + /// - `IOException`: if an I/O error occurs. Appendable append(char c) throws IOException; - /** - * Appends the character sequence {@code csq}. Implementation classes may - * not append the whole sequence, for example if the target is a buffer with - * limited size. - *

- * If {@code csq} is {@code null}, the characters "null" are appended. - * - * @param csq - * the character sequence to append. - * @return this {@code Appendable}. - * @throws IOException - * if an I/O error occurs. - */ + /// Appends the character sequence `csq`. Implementation classes may + /// not append the whole sequence, for example if the target is a buffer with + /// limited size. + /// + /// If `csq` is `null`, the characters "null" are appended. + /// + /// #### Parameters + /// + /// - `csq`: the character sequence to append. + /// + /// #### Returns + /// + /// this `Appendable`. + /// + /// #### Throws + /// + /// - `IOException`: if an I/O error occurs. Appendable append(CharSequence csq) throws IOException; - /** - * Appends a subsequence of {@code csq}. - *

- * If {@code csq} is not {@code null} then calling this method is equivalent - * to calling {@code append(csq.subSequence(start, end))}. - *

- * If {@code csq} is {@code null}, the characters "null" are appended. - * - * @param csq - * the character sequence to append. - * @param start - * the first index of the subsequence of {@code csq} that is - * appended. - * @param end - * the last index of the subsequence of {@code csq} that is - * appended. - * @return this {@code Appendable}. - * @throws IndexOutOfBoundsException - * if {@code start < 0}, {@code end < 0}, {@code start > end} - * or {@code end} is greater than the length of {@code csq}. - * @throws IOException - * if an I/O error occurs. - */ + /// Appends a subsequence of `csq`. + /// + /// If `csq` is not `null` then calling this method is equivalent + /// to calling `append(csq.subSequence(start, end))`. + /// + /// If `csq` is `null`, the characters "null" are appended. + /// + /// #### Parameters + /// + /// - `csq`: the character sequence to append. + /// + /// - `start`: @param start + /// the first index of the subsequence of `csq` that is + /// appended. + /// + /// - `end`: @param end + /// the last index of the subsequence of `csq` that is + /// appended. + /// + /// #### Returns + /// + /// this `Appendable`. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `start end` + /// or `end` is greater than the length of `csq`. + /// + /// - `IOException`: if an I/O error occurs. Appendable append(CharSequence csq, int start, int end) throws IOException; } diff --git a/Ports/CLDC11/src/java/lang/ArithmeticException.java b/Ports/CLDC11/src/java/lang/ArithmeticException.java index c56b101a6b..87a242a9c1 100644 --- a/Ports/CLDC11/src/java/lang/ArithmeticException.java +++ b/Ports/CLDC11/src/java/lang/ArithmeticException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown when an exceptional arithmetic condition has occurred. For example, an integer "divide by zero" throws an instance of this class. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown when an exceptional arithmetic condition has occurred. For example, an integer "divide by zero" throws an instance of this class. +/// Since: JDK1.0, CLDC 1.0 public class ArithmeticException extends java.lang.RuntimeException{ - /** - * Constructs an ArithmeticException with no detail message. - */ + /// Constructs an ArithmeticException with no detail message. public ArithmeticException(){ //TODO codavaj!! } - /** - * Constructs an ArithmeticException with the specified detail message. - * s - the detail message. - */ + /// Constructs an ArithmeticException with the specified detail message. + /// s - the detail message. public ArithmeticException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/ArrayIndexOutOfBoundsException.java b/Ports/CLDC11/src/java/lang/ArrayIndexOutOfBoundsException.java index e94938290d..eef2f2963a 100644 --- a/Ports/CLDC11/src/java/lang/ArrayIndexOutOfBoundsException.java +++ b/Ports/CLDC11/src/java/lang/ArrayIndexOutOfBoundsException.java @@ -22,30 +22,22 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that an array has been accessed with an illegal index. The index is either negative or greater than or equal to the size of the array. +/// Since: JDK1.0, CLDC 1.0 public class ArrayIndexOutOfBoundsException extends java.lang.IndexOutOfBoundsException{ - /** - * Constructs an ArrayIndexOutOfBoundsException with no detail message. - */ + /// Constructs an ArrayIndexOutOfBoundsException with no detail message. public ArrayIndexOutOfBoundsException(){ //TODO codavaj!! } - /** - * Constructs a new ArrayIndexOutOfBoundsException class with an argument indicating the illegal index. - * index - the illegal index. - */ + /// Constructs a new ArrayIndexOutOfBoundsException class with an argument indicating the illegal index. + /// index - the illegal index. public ArrayIndexOutOfBoundsException(int index){ //TODO codavaj!! } - /** - * Constructs an ArrayIndexOutOfBoundsException class with the specified detail message. - * s - the detail message. - */ + /// Constructs an ArrayIndexOutOfBoundsException class with the specified detail message. + /// s - the detail message. public ArrayIndexOutOfBoundsException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/ArrayStoreException.java b/Ports/CLDC11/src/java/lang/ArrayStoreException.java index 5f64cce0ad..c1f584ec45 100644 --- a/Ports/CLDC11/src/java/lang/ArrayStoreException.java +++ b/Ports/CLDC11/src/java/lang/ArrayStoreException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that an attempt has been made to store the wrong type of object into an array of objects. For example, the following code generates an ArrayStoreException: - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that an attempt has been made to store the wrong type of object into an array of objects. For example, the following code generates an ArrayStoreException: +/// Since: JDK1.0, CLDC 1.0 public class ArrayStoreException extends java.lang.RuntimeException{ - /** - * Constructs an ArrayStoreException with no detail message. - */ + /// Constructs an ArrayStoreException with no detail message. public ArrayStoreException(){ //TODO codavaj!! } - /** - * Constructs an ArrayStoreException with the specified detail message. - * s - the detail message. - */ + /// Constructs an ArrayStoreException with the specified detail message. + /// s - the detail message. public ArrayStoreException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/AssertionError.java b/Ports/CLDC11/src/java/lang/AssertionError.java index 93e2d59962..fd3cc9819d 100644 --- a/Ports/CLDC11/src/java/lang/AssertionError.java +++ b/Ports/CLDC11/src/java/lang/AssertionError.java @@ -23,10 +23,7 @@ */ package java.lang; -/** - * - * @author shai - */ +/// @author shai public class AssertionError extends Error { public AssertionError() { super(); diff --git a/Ports/CLDC11/src/java/lang/Boolean.java b/Ports/CLDC11/src/java/lang/Boolean.java index 2a37f37e53..b06e8237fc 100644 --- a/Ports/CLDC11/src/java/lang/Boolean.java +++ b/Ports/CLDC11/src/java/lang/Boolean.java @@ -22,62 +22,50 @@ * have any questions. */ package java.lang; -/** - * The Boolean class wraps a value of the primitive type boolean in an object. An object of type Boolean contains a single field whose type is boolean. - * Since: JDK1.0, CLDC 1.0 - */ +/// The Boolean class wraps a value of the primitive type boolean in an object. An object of type Boolean contains a single field whose type is boolean. +/// Since: JDK1.0, CLDC 1.0 public final class Boolean{ - /** - * The Boolean object corresponding to the primitive value false. - */ + /// The Boolean object corresponding to the primitive value false. public static final java.lang.Boolean FALSE=null; - /** - * The Boolean object corresponding to the primitive value true. - */ + /// The Boolean object corresponding to the primitive value true. public static final java.lang.Boolean TRUE=null; - /** - * Allocates a Boolean object representing the value argument. - * value - the value of the Boolean. - */ + /// Allocates a Boolean object representing the value argument. + /// value - the value of the Boolean. public Boolean(boolean value){ //TODO codavaj!! } - /** - * Returns the value of this Boolean object as a boolean primitive. - */ + /// Returns the value of this Boolean object as a boolean primitive. public boolean booleanValue(){ return false; //TODO codavaj!! } - /** - * Returns true if and only if the argument is not null and is a Boolean object that represents the same boolean value as this object. - */ + /// Returns true if and only if the argument is not null and is a Boolean object that represents the same boolean value as this object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns a hash code for this Boolean object. - */ + /// Returns a hash code for this Boolean object. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns a String object representing this Boolean's value. If this object represents the value true, a string equal to "true" is returned. Otherwise, a string equal to "false" is returned. - */ + /// Returns a String object representing this Boolean's value. If this object represents the value true, a string equal to "true" is returned. Otherwise, a string equal to "false" is returned. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param b the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `b`: the primitive + /// + /// #### Returns + /// + /// object instance public static Boolean valueOf(final boolean b) { return b ? Boolean.TRUE : Boolean.FALSE; } diff --git a/Ports/CLDC11/src/java/lang/Byte.java b/Ports/CLDC11/src/java/lang/Byte.java index 9bf1c14c0f..76bac16f98 100644 --- a/Ports/CLDC11/src/java/lang/Byte.java +++ b/Ports/CLDC11/src/java/lang/Byte.java @@ -22,81 +22,65 @@ * have any questions. */ package java.lang; -/** - * The Byte class is the standard wrapper for byte values. - * Since: JDK1.1, CLDC 1.0 - */ +/// The Byte class is the standard wrapper for byte values. +/// Since: JDK1.1, CLDC 1.0 public final class Byte extends Number implements Comparable { public static final Class TYPE = byte.class; public static final int SIZE = 8; - /** - * The maximum value a Byte can have. - * See Also:Constant Field Values - */ + /// The maximum value a Byte can have. + /// See Also:Constant Field Values public static final byte MAX_VALUE=127; - /** - * The minimum value a Byte can have. - * See Also:Constant Field Values - */ + /// The minimum value a Byte can have. + /// See Also:Constant Field Values public static final byte MIN_VALUE=-128; - /** - * Constructs a Byte object initialized to the specified byte value. - * value - the initial value of the Byte - */ + /// Constructs a Byte object initialized to the specified byte value. + /// value - the initial value of the Byte public Byte(byte value){ //TODO codavaj!! } - /** - * Returns the value of this Byte as a byte. - */ + /// Returns the value of this Byte as a byte. public byte byteValue(){ return 0; //TODO codavaj!! } - /** - * Compares this object to the specified object. - */ + /// Compares this object to the specified object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns a hashcode for this Byte. - */ + /// Returns a hashcode for this Byte. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte. The radix is assumed to be 10. - */ + /// Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte. The radix is assumed to be 10. public static byte parseByte(java.lang.String s) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte. - */ + /// Assuming the specified String represents a byte, returns that byte's value. Throws an exception if the String cannot be parsed as a byte. public static byte parseByte(java.lang.String s, int radix) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Returns a String object representing this Byte's value. - */ + /// Returns a String object representing this Byte's value. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Byte valueOf(byte i) { return null; } diff --git a/Ports/CLDC11/src/java/lang/CharSequence.java b/Ports/CLDC11/src/java/lang/CharSequence.java index c763765ffe..a84f1d9c02 100644 --- a/Ports/CLDC11/src/java/lang/CharSequence.java +++ b/Ports/CLDC11/src/java/lang/CharSequence.java @@ -18,57 +18,67 @@ package java.lang; -/** - * This interface represents an ordered set of characters and defines the - * methods to probe them. - */ +/// This interface represents an ordered set of characters and defines the +/// methods to probe them. public interface CharSequence { - /** - * Returns the number of characters in this sequence. - * - * @return the number of characters. - */ + /// Returns the number of characters in this sequence. + /// + /// #### Returns + /// + /// the number of characters. public int length(); - /** - * Returns the character at the specified index, with the first character - * having index zero. - * - * @param index - * the index of the character to return. - * @return the requested character. - * @throws IndexOutOfBoundsException - * if {@code index < 0} or {@code index} is greater than the - * length of this sequence. - */ + /// Returns the character at the specified index, with the first character + /// having index zero. + /// + /// #### Parameters + /// + /// - `index`: the index of the character to return. + /// + /// #### Returns + /// + /// the requested character. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `index < 0` or `index` is greater than the + /// length of this sequence. public char charAt(int index); - /** - * Returns a {@code CharSequence} from the {@code start} index (inclusive) - * to the {@code end} index (exclusive) of this sequence. - * - * @param start - * the start offset of the sub-sequence. It is inclusive, that - * is, the index of the first character that is included in the - * sub-sequence. - * @param end - * the end offset of the sub-sequence. It is exclusive, that is, - * the index of the first character after those that are included - * in the sub-sequence - * @return the requested sub-sequence. - * @throws IndexOutOfBoundsException - * if {@code start < 0}, {@code end < 0}, {@code start > end}, - * or if {@code start} or {@code end} are greater than the - * length of this sequence. - */ + /// Returns a `CharSequence` from the `start` index (inclusive) + /// to the `end` index (exclusive) of this sequence. + /// + /// #### Parameters + /// + /// - `start`: @param start + /// the start offset of the sub-sequence. It is inclusive, that + /// is, the index of the first character that is included in the + /// sub-sequence. + /// + /// - `end`: @param end + /// the end offset of the sub-sequence. It is exclusive, that is, + /// the index of the first character after those that are included + /// in the sub-sequence + /// + /// #### Returns + /// + /// the requested sub-sequence. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `start end`, + /// or if `start` or `end` are greater than the + /// length of this sequence. public CharSequence subSequence(int start, int end); - /** - * Returns a string with the same characters in the same order as in this - * sequence. - * - * @return a string based on this sequence. - */ + /// Returns a string with the same characters in the same order as in this + /// sequence. + /// + /// #### Returns + /// + /// a string based on this sequence. public String toString(); } diff --git a/Ports/CLDC11/src/java/lang/Character.java b/Ports/CLDC11/src/java/lang/Character.java index a136ea0bfd..0d937bd21d 100644 --- a/Ports/CLDC11/src/java/lang/Character.java +++ b/Ports/CLDC11/src/java/lang/Character.java @@ -22,352 +22,342 @@ * have any questions. */ package java.lang; -/** - * The Character class wraps a value of the primitive type char in an object. An object of type Character contains a single field whose type is char. - * In addition, this class provides several methods for determining the type of a character and converting characters from uppercase to lowercase and vice versa. - * Character information is based on the Unicode Standard, version 3.0. However, in order to reduce footprint, by default the character property and case conversion operations in CLDC are available only for the ISO Latin-1 range of characters. Other Unicode character blocks can be supported as necessary. - * Since: JDK1.0, CLDC 1.0 - */ +/// The Character class wraps a value of the primitive type char in an object. An object of type Character contains a single field whose type is char. +/// In addition, this class provides several methods for determining the type of a character and converting characters from uppercase to lowercase and vice versa. +/// Character information is based on the Unicode Standard, version 3.0. However, in order to reduce footprint, by default the character property and case conversion operations in CLDC are available only for the ISO Latin-1 range of characters. Other Unicode character blocks can be supported as necessary. +/// Since: JDK1.0, CLDC 1.0 public final class Character{ - /** - * The maximum radix available for conversion to and from Strings. - * See Also:Integer.toString(int, int), Integer.valueOf(java.lang.String), Constant Field Values - */ + /// The maximum radix available for conversion to and from Strings. + /// See Also:Integer.toString(int, int), Integer.valueOf(java.lang.String), Constant Field Values public static final int MAX_RADIX=36; - /** - * The constant value of this field is the largest value of type char. - * Since: JDK1.0.2 See Also:Constant Field Values - */ + /// The constant value of this field is the largest value of type char. + /// Since: JDK1.0.2 See Also:Constant Field Values public static final char MAX_VALUE=(char)65535; - /** - * The minimum radix available for conversion to and from Strings. - * See Also:Integer.toString(int, int), Integer.valueOf(java.lang.String), Constant Field Values - */ + /// The minimum radix available for conversion to and from Strings. + /// See Also:Integer.toString(int, int), Integer.valueOf(java.lang.String), Constant Field Values public static final int MIN_RADIX=2; - /** - * The constant value of this field is the smallest value of type char. - * Since: JDK1.0.2 See Also:Constant Field Values - */ + /// The constant value of this field is the smallest value of type char. + /// Since: JDK1.0.2 See Also:Constant Field Values public static final char MIN_VALUE=(char)0; - /** - * Constructs a Character object and initializes it so that it represents the primitive value argument. - * value - value for the new Character object. - */ + /// Constructs a Character object and initializes it so that it represents the primitive value argument. + /// value - value for the new Character object. public Character(char value){ //TODO codavaj!! } - /** - * Returns the value of this Character object. - */ + /// Returns the value of this Character object. public char charValue(){ return ' '; //TODO codavaj!! } - /** - * Returns the numeric value of the character ch in the specified radix. - */ + /// Returns the numeric value of the character ch in the specified radix. public static int digit(char ch, int radix){ return 0; //TODO codavaj!! } - /** - * Compares this object against the specified object. The result is true if and only if the argument is not null and is a Character object that represents the same char value as this object. - */ + /// Compares this object against the specified object. The result is true if and only if the argument is not null and is a Character object that represents the same char value as this object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns a hash code for this Character. - */ + /// Returns a hash code for this Character. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Determines if the specified character is alphabetic. - */ + /// Determines if the specified character is alphabetic. static boolean isLetterCompat(char ch){ return isLowerCase(ch) || isUpperCase(ch); } - /** - * Determines if the specified character is numeric. - */ + /// Determines if the specified character is numeric. static boolean isDigitCompat(char ch){ return isDigit(ch); } - /** - * Determines if the specified character is alphabetic or numeric. - */ + /// Determines if the specified character is alphabetic or numeric. static boolean isLetterOrDigitCompat(char ch){ return isLetterCompat(ch) || isDigitCompat(ch); } - /** - * Determines if the specified character is a digit. - */ + /// Determines if the specified character is a digit. public static boolean isDigit(char ch){ return false; //TODO codavaj!! } - /** - * Determines if the specified character is a lowercase character. - * Note that by default CLDC only supports the ISO Latin-1 range of characters. - * Of the ISO Latin-1 characters (character codes 0x0000 through 0x00FF), the following are lowercase: - * a b c d e f g h i j k l m n o p q r s t u v w x y z u00DF u00E0 u00E1 u00E2 u00E3 u00E4 u00E5 u00E6 u00E7 u00E8 u00E9 u00EA u00EB u00EC u00ED u00EE u00EF u00F0 u00F1 u00F2 u00F3 u00F4 u00F5 u00F6 u00F8 u00F9 u00FA u00FB u00FC u00FD u00FE u00FF - */ + /// Determines if the specified character is a lowercase character. + /// Note that by default CLDC only supports the ISO Latin-1 range of characters. + /// Of the ISO Latin-1 characters (character codes 0x0000 through 0x00FF), the following are lowercase: + /// a b c d e f g h i j k l m n o p q r s t u v w x y z u00DF u00E0 u00E1 u00E2 u00E3 u00E4 u00E5 u00E6 u00E7 u00E8 u00E9 u00EA u00EB u00EC u00ED u00EE u00EF u00F0 u00F1 u00F2 u00F3 u00F4 u00F5 u00F6 u00F8 u00F9 u00FA u00FB u00FC u00FD u00FE u00FF public static boolean isLowerCase(char ch){ return false; //TODO codavaj!! } - /** - * Determines if the specified character is an uppercase character. - * Note that by default CLDC only supports the ISO Latin-1 range of characters. - * Of the ISO Latin-1 characters (character codes 0x0000 through 0x00FF), the following are uppercase: - * A B C D E F G H I J K L M N O P Q R S T U V W X Y Z u00C0 u00C1 u00C2 u00C3 u00C4 u00C5 u00C6 u00C7 u00C8 u00C9 u00CA u00CB u00CC u00CD u00CE u00CF u00D0 u00D1 u00D2 u00D3 u00D4 u00D5 u00D6 u00D8 u00D9 u00DA u00DB u00DC u00DD u00DE - */ + /// Determines if the specified character is an uppercase character. + /// Note that by default CLDC only supports the ISO Latin-1 range of characters. + /// Of the ISO Latin-1 characters (character codes 0x0000 through 0x00FF), the following are uppercase: + /// A B C D E F G H I J K L M N O P Q R S T U V W X Y Z u00C0 u00C1 u00C2 u00C3 u00C4 u00C5 u00C6 u00C7 u00C8 u00C9 u00CA u00CB u00CC u00CD u00CE u00CF u00D0 u00D1 u00D2 u00D3 u00D4 u00D5 u00D6 u00D8 u00D9 u00DA u00DB u00DC u00DD u00DE public static boolean isUpperCase(char ch){ return false; //TODO codavaj!! } - /** - * The given character is mapped to its lowercase equivalent; if the character has no lowercase equivalent, the character itself is returned. - * Note that by default CLDC only supports the ISO Latin-1 range of characters. - */ + /// The given character is mapped to its lowercase equivalent; if the character has no lowercase equivalent, the character itself is returned. + /// Note that by default CLDC only supports the ISO Latin-1 range of characters. public static char toLowerCase(char ch){ return ' '; //TODO codavaj!! } - /** - * Returns a String object representing this character's value. Converts this Character object to a string. The result is a string whose length is 1. The string's sole component is the primitive char value represented by this object. - */ + /// Returns a String object representing this character's value. Converts this Character object to a string. The result is a string whose length is 1. The string's sole component is the primitive char value represented by this object. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Converts the character argument to uppercase; if the character has no uppercase equivalent, the character itself is returned. - * Note that by default CLDC only supports the ISO Latin-1 range of characters. - */ + /// Converts the character argument to uppercase; if the character has no uppercase equivalent, the character itself is returned. + /// Note that by default CLDC only supports the ISO Latin-1 range of characters. public static char toUpperCase(char ch){ return ' '; //TODO codavaj!! } - /** - *

- * Minimum value of a high surrogate or leading surrogate unit in UTF-16 - * encoding - '\uD800'. - *

- * - * @since 1.5 - */ + /// Minimum value of a high surrogate or leading surrogate unit in UTF-16 + /// encoding - `'\uD800'`. + /// + /// #### Since + /// + /// 1.5 public static final char MIN_HIGH_SURROGATE = '\uD800'; - /** - *

- * Maximum value of a high surrogate or leading surrogate unit in UTF-16 - * encoding - '\uDBFF'. - *

- * - * @since 1.5 - */ + /// Maximum value of a high surrogate or leading surrogate unit in UTF-16 + /// encoding - `'\uDBFF'`. + /// + /// #### Since + /// + /// 1.5 public static final char MAX_HIGH_SURROGATE = '\uDBFF'; - /** - *

- * Minimum value of a low surrogate or trailing surrogate unit in UTF-16 - * encoding - '\uDC00'. - *

- * - * @since 1.5 - */ + /// Minimum value of a low surrogate or trailing surrogate unit in UTF-16 + /// encoding - `'\uDC00'`. + /// + /// #### Since + /// + /// 1.5 public static final char MIN_LOW_SURROGATE = '\uDC00'; - /** - * Maximum value of a low surrogate or trailing surrogate unit in UTF-16 - * encoding - '\uDFFF'. - *

- * - * @since 1.5 - */ + /// Maximum value of a low surrogate or trailing surrogate unit in UTF-16 + /// encoding - `'\uDFFF'`. + /// + /// #### Since + /// + /// 1.5 public static final char MAX_LOW_SURROGATE = '\uDFFF'; - /** - *

- * Minimum value of a surrogate unit in UTF-16 encoding - '\uD800'. - *

- * - * @since 1.5 - */ + /// Minimum value of a surrogate unit in UTF-16 encoding - `'\uD800'`. + /// + /// #### Since + /// + /// 1.5 public static final char MIN_SURROGATE = '\uD800'; - /** - *

- * Maximum value of a surrogate unit in UTF-16 encoding - '\uDFFF'. - *

- * - * @since 1.5 - */ + /// Maximum value of a surrogate unit in UTF-16 encoding - `'\uDFFF'`. + /// + /// #### Since + /// + /// 1.5 public static final char MAX_SURROGATE = '\uDFFF'; - /** - *

- * Minimum value of a supplementary code point - U+010000. - *

- * - * @since 1.5 - */ + /// Minimum value of a supplementary code point - `U+010000`. + /// + /// #### Since + /// + /// 1.5 public static final int MIN_SUPPLEMENTARY_CODE_POINT = 0x10000; - /** - *

- * Minimum code point value - U+0000. - *

- * - * @since 1.5 - */ + /// Minimum code point value - `U+0000`. + /// + /// #### Since + /// + /// 1.5 public static final int MIN_CODE_POINT = 0x000000; - /** - *

- * Maximum code point value - U+10FFFF. - *

- * - * @since 1.5 - */ + /// Maximum code point value - `U+10FFFF`. + /// + /// #### Since + /// + /// 1.5 public static final int MAX_CODE_POINT = 0x10FFFF; - /** - *

- * Constant for the number of bits to represent a char in - * two's compliment form. - *

- * - * @since 1.5 - */ + /// Constant for the number of bits to represent a `char` in + /// two's compliment form. + /// + /// #### Since + /// + /// 1.5 public static final int SIZE = 16; - /** - *

- * A test for determining if the codePoint is a valid Unicode - * code point. - *

- * - * @param codePoint The code point to test. - * @return A boolean value. - * @since 1.5 - */ + /// A test for determining if the `codePoint` is a valid Unicode + /// code point. + /// + /// #### Parameters + /// + /// - `codePoint`: The code point to test. + /// + /// #### Returns + /// + /// A boolean value. + /// + /// #### Since + /// + /// 1.5 public static boolean isValidCodePoint(int codePoint) { return (MIN_CODE_POINT <= codePoint && MAX_CODE_POINT >= codePoint); } - /** - *

- * A test for determining if the codePoint is within the - * supplementary code point range. - *

- * - * @param codePoint The code point to test. - * @return A boolean value. - * @since 1.5 - */ + /// A test for determining if the `codePoint` is within the + /// supplementary code point range. + /// + /// #### Parameters + /// + /// - `codePoint`: The code point to test. + /// + /// #### Returns + /// + /// A boolean value. + /// + /// #### Since + /// + /// 1.5 public static boolean isSupplementaryCodePoint(int codePoint) { return (MIN_SUPPLEMENTARY_CODE_POINT <= codePoint && MAX_CODE_POINT >= codePoint); } - /** - *

- * A test for determining if the char is a high - * surrogate/leading surrogate unit that's used for representing - * supplementary characters in UTF-16 encoding. - *

- * - * @param ch The char unit to test. - * @return A boolean value. - * @since 1.5 - * @see #isLowSurrogate(char) - */ + /// A test for determining if the `char` is a high + /// surrogate/leading surrogate unit that's used for representing + /// supplementary characters in UTF-16 encoding. + /// + /// #### Parameters + /// + /// - `ch`: The `char` unit to test. + /// + /// #### Returns + /// + /// A boolean value. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #isLowSurrogate(char) public static boolean isHighSurrogate(char ch) { return (MIN_HIGH_SURROGATE <= ch && MAX_HIGH_SURROGATE >= ch); } - /** - *

- * A test for determining if the char is a high - * surrogate/leading surrogate unit that's used for representing - * supplementary characters in UTF-16 encoding. - *

- * - * @param ch The char unit to test. - * @return A boolean value. - * @since 1.5 - * @see #isHighSurrogate(char) - */ + /// A test for determining if the `char` is a high + /// surrogate/leading surrogate unit that's used for representing + /// supplementary characters in UTF-16 encoding. + /// + /// #### Parameters + /// + /// - `ch`: The `char` unit to test. + /// + /// #### Returns + /// + /// A boolean value. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #isHighSurrogate(char) public static boolean isLowSurrogate(char ch) { return (MIN_LOW_SURROGATE <= ch && MAX_LOW_SURROGATE >= ch); } - /** - *

- * A test for determining if the char pair is a valid - * surrogate pair. - *

- * - * @param high The high surrogate unit to test. - * @param low The low surrogate unit to test. - * @return A boolean value. - * @since 1.5 - * @see #isHighSurrogate(char) - * @see #isLowSurrogate(char) - */ + /// A test for determining if the `char` pair is a valid + /// surrogate pair. + /// + /// #### Parameters + /// + /// - `high`: The high surrogate unit to test. + /// + /// - `low`: The low surrogate unit to test. + /// + /// #### Returns + /// + /// A boolean value. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #isHighSurrogate(char) + /// + /// - #isLowSurrogate(char) public static boolean isSurrogatePair(char high, char low) { return (isHighSurrogate(high) && isLowSurrogate(low)); } - /** - *

- * Calculates the number of char values required to represent - * the Unicode code point. This method only tests if the - * codePoint is greater than or equal to 0x10000, - * in which case 2 is returned, otherwise 1. - * To test if the code point is valid, use the - * {@link #isValidCodePoint(int)} method. - *

- * - * @param codePoint The code point to test. - * @return An int value of 2 or 1. - * @since 1.5 - * @see #isValidCodePoint(int) - * @see #isSupplementaryCodePoint(int) - */ + /// Calculates the number of `char` values required to represent + /// the Unicode code point. This method only tests if the + /// `codePoint` is greater than or equal to `0x10000`, + /// in which case `2` is returned, otherwise `1`. + /// To test if the code point is valid, use the + /// `#isValidCodePoint(int)` method. + /// + /// #### Parameters + /// + /// - `codePoint`: The code point to test. + /// + /// #### Returns + /// + /// An `int` value of 2 or 1. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #isValidCodePoint(int) + /// + /// - #isSupplementaryCodePoint(int) public static int charCount(int codePoint) { return (codePoint >= 0x10000 ? 2 : 1); } - /** - *

- * Converts a surrogate pair into a Unicode code point. This method assume - * that the pair are valid surrogates. If the pair are NOT valid surrogates, - * then the result is indeterminate. The - * {@link #isSurrogatePair(char, char)} method should be used prior to this - * method to validate the pair. - *

- * - * @param high The high surrogate unit. - * @param low The low surrogate unit. - * @return The decoded code point. - * @since 1.5 - * @see #isSurrogatePair(char, char) - */ + /// Converts a surrogate pair into a Unicode code point. This method assume + /// that the pair are valid surrogates. If the pair are NOT valid surrogates, + /// then the result is indeterminate. The + /// `char)` method should be used prior to this + /// method to validate the pair. + /// + /// #### Parameters + /// + /// - `high`: The high surrogate unit. + /// + /// - `low`: The low surrogate unit. + /// + /// #### Returns + /// + /// The decoded code point. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #isSurrogatePair(char, char) public static int toCodePoint(char high, char low) { // See RFC 2781, Section 2.2 // http://www.faqs.org/rfcs/rfc2781.html @@ -376,25 +366,34 @@ public static int toCodePoint(char high, char low) { return (h | l) + 0x10000; } - /** - *

- * Returns the code point at the index in the CharSequence. - * If char unit at the index is a high-surrogate unit, the - * next index is less than the length of the sequence and the - * char unit at the next index is a low surrogate unit, then - * the code point represented by the pair is returned; otherwise the - * char unit at the index is returned. - *

- * - * @param seq The sequence of char units. - * @param index The index into the seq to retrieve and - * convert. - * @return The Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if the index is negative - * or greater than or equal to seq.length(). - * @since 1.5 - */ + /// Returns the code point at the index in the `CharSequence`. + /// If `char` unit at the index is a high-surrogate unit, the + /// next index is less than the length of the sequence and the + /// `char` unit at the next index is a low surrogate unit, then + /// the code point represented by the pair is returned; otherwise the + /// `char` unit at the index is returned. + /// + /// #### Parameters + /// + /// - `seq`: The sequence of `char` units. + /// + /// - `index`: @param index The index into the `seq` to retrieve and + /// convert. + /// + /// #### Returns + /// + /// The Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if the `index` is negative + /// or greater than or equal to `seq.length()`. + /// + /// #### Since + /// + /// 1.5 public static int codePointAt(CharSequence seq, int index) { if (seq == null) { throw new NullPointerException(); @@ -415,25 +414,34 @@ public static int codePointAt(CharSequence seq, int index) { return high; } - /** - *

- * Returns the code point at the index in the char[]. If - * char unit at the index is a high-surrogate unit, the next - * index is less than the length of the sequence and the char - * unit at the next index is a low surrogate unit, then the code point - * represented by the pair is returned; otherwise the char - * unit at the index is returned. - *

- * - * @param seq The sequence of char units. - * @param index The index into the seq to retrieve and - * convert. - * @return The Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if the index is negative - * or greater than or equal to seq.length(). - * @since 1.5 - */ + /// Returns the code point at the index in the `char[]`. If + /// `char` unit at the index is a high-surrogate unit, the next + /// index is less than the length of the sequence and the `char` + /// unit at the next index is a low surrogate unit, then the code point + /// represented by the pair is returned; otherwise the `char` + /// unit at the index is returned. + /// + /// #### Parameters + /// + /// - `seq`: The sequence of `char` units. + /// + /// - `index`: @param index The index into the `seq` to retrieve and + /// convert. + /// + /// #### Returns + /// + /// The Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if the `index` is negative + /// or greater than or equal to `seq.length()`. + /// + /// #### Since + /// + /// 1.5 public static int codePointAt(char[] seq, int index) { if (seq == null) { throw new NullPointerException(); @@ -454,29 +462,39 @@ public static int codePointAt(char[] seq, int index) { return high; } - /** - *

- * Returns the code point at the index in the char[] that's - * within the limit. If char unit at the index is a - * high-surrogate unit, the next index is less than the limit - * and the char unit at the next index is a low surrogate - * unit, then the code point represented by the pair is returned; otherwise - * the char unit at the index is returned. - *

- * - * @param seq The sequence of char units. - * @param index The index into the seq to retrieve and - * convert. - * @param limit The exclusive index into the seq that marks - * the end of the units that can be used. - * @return The Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if the index is - * negative, greater than or equal to limit, - * limit is negative or limit is - * greater than the length of seq. - * @since 1.5 - */ + /// Returns the code point at the index in the `char[]` that's + /// within the limit. If `char` unit at the index is a + /// high-surrogate unit, the next index is less than the `limit` + /// and the `char` unit at the next index is a low surrogate + /// unit, then the code point represented by the pair is returned; otherwise + /// the `char` unit at the index is returned. + /// + /// #### Parameters + /// + /// - `seq`: The sequence of `char` units. + /// + /// - `index`: @param index The index into the `seq` to retrieve and + /// convert. + /// + /// - `limit`: @param limit The exclusive index into the `seq` that marks + /// the end of the units that can be used. + /// + /// #### Returns + /// + /// The Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if the `index` is + /// negative, greater than or equal to `limit`, + /// `limit` is negative or `limit` is + /// greater than the length of `seq`. + /// + /// #### Since + /// + /// 1.5 public static int codePointAt(char[] seq, int index, int limit) { if (index < 0 || index >= limit || limit < 0 || limit > seq.length) { throw new IndexOutOfBoundsException(); @@ -493,26 +511,35 @@ public static int codePointAt(char[] seq, int index, int limit) { return high; } - /** - *

- * Returns the Unicode code point that proceeds the index in - * the CharSequence. If the char unit at - * index - 1 is within the low surrogate range, the value - * index - 2 isn't negative and the char unit - * at index - 2 is within the high surrogate range, then the - * supplementary code point made up of the surrogate pair is returned; - * otherwise, the char value at index - 1 is - * returned. - *

- * - * @param seq The CharSequence to search. - * @param index The index into the seq. - * @return A Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if index is less than 1 - * or greater than seq.length(). - * @since 1.5 - */ + /// Returns the Unicode code point that proceeds the `index` in + /// the `CharSequence`. If the `char` unit at + /// `index - 1` is within the low surrogate range, the value + /// `index - 2` isn't negative and the `char` unit + /// at `index - 2` is within the high surrogate range, then the + /// supplementary code point made up of the surrogate pair is returned; + /// otherwise, the `char` value at `index - 1` is + /// returned. + /// + /// #### Parameters + /// + /// - `seq`: The `CharSequence` to search. + /// + /// - `index`: The index into the `seq`. + /// + /// #### Returns + /// + /// A Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is less than 1 + /// or greater than `seq.length()`. + /// + /// #### Since + /// + /// 1.5 public static int codePointBefore(CharSequence seq, int index) { if (seq == null) { throw new NullPointerException(); @@ -533,26 +560,35 @@ public static int codePointBefore(CharSequence seq, int index) { return low; } - /** - *

- * Returns the Unicode code point that proceeds the index in - * the char[]. If the char unit at - * index - 1 is within the low surrogate range, the value - * index - 2 isn't negative and the char unit - * at index - 2 is within the high surrogate range, then the - * supplementary code point made up of the surrogate pair is returned; - * otherwise, the char value at index - 1 is - * returned. - *

- * - * @param seq The char[] to search. - * @param index The index into the seq. - * @return A Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if index is less than 1 - * or greater than seq.length. - * @since 1.5 - */ + /// Returns the Unicode code point that proceeds the `index` in + /// the `char[]`. If the `char` unit at + /// `index - 1` is within the low surrogate range, the value + /// `index - 2` isn't negative and the `char` unit + /// at `index - 2` is within the high surrogate range, then the + /// supplementary code point made up of the surrogate pair is returned; + /// otherwise, the `char` value at `index - 1` is + /// returned. + /// + /// #### Parameters + /// + /// - `seq`: The `char[]` to search. + /// + /// - `index`: The index into the `seq`. + /// + /// #### Returns + /// + /// A Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is less than 1 + /// or greater than `seq.length`. + /// + /// #### Since + /// + /// 1.5 public static int codePointBefore(char[] seq, int index) { if (seq == null) { throw new NullPointerException(); @@ -573,30 +609,39 @@ public static int codePointBefore(char[] seq, int index) { return low; } - /** - *

- * Returns the Unicode code point that proceeds the index in - * the char[] and isn't less than start. If - * the char unit at index - 1 is within the - * low surrogate range, the value index - 2 isn't less than - * start and the char unit at - * index - 2 is within the high surrogate range, then the - * supplementary code point made up of the surrogate pair is returned; - * otherwise, the char value at index - 1 is - * returned. - *

- * - * @param seq The char[] to search. - * @param index The index into the seq. - * @return A Unicode code point. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if index is less than or - * equal to start, index is greater - * than seq.length, start is not - * negative and start is greater than - * seq.length. - * @since 1.5 - */ + /// Returns the Unicode code point that proceeds the `index` in + /// the `char[]` and isn't less than `start`. If + /// the `char` unit at `index - 1` is within the + /// low surrogate range, the value `index - 2` isn't less than + /// `start` and the `char` unit at + /// `index - 2` is within the high surrogate range, then the + /// supplementary code point made up of the surrogate pair is returned; + /// otherwise, the `char` value at `index - 1` is + /// returned. + /// + /// #### Parameters + /// + /// - `seq`: The `char[]` to search. + /// + /// - `index`: The index into the `seq`. + /// + /// #### Returns + /// + /// A Unicode code point. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is less than or + /// equal to `start`, `index` is greater + /// than `seq.length`, `start` is not + /// negative and `start` is greater than + /// `seq.length`. + /// + /// #### Since + /// + /// 1.5 public static int codePointBefore(char[] seq, int index, int start) { if (seq == null) { throw new NullPointerException(); @@ -617,28 +662,39 @@ public static int codePointBefore(char[] seq, int index, int start) { return low; } - /** - *

- * Converts the Unicode code point, codePoint, into a UTF-16 - * encoded sequence and copies the value(s) into the - * char[] dst, starting at the index - * dstIndex. - *

- * - * @param codePoint The Unicode code point to encode. - * @param dst The char[] to copy the encoded value into. - * @param dstIndex The index to start copying into dst. - * @return The number of char value units copied into - * dst. - * @throws IllegalArgumentException if codePoint is not a - * valid Unicode code point. - * @throws NullPointerException if dst is null. - * @throws IndexOutOfBoundsException if dstIndex is negative, - * greater than or equal to dst.length or equals - * dst.length - 1 when codePoint is a - * {@link #isSupplementaryCodePoint(int) supplementary code point}. - * @since 1.5 - */ + /// Converts the Unicode code point, `codePoint`, into a UTF-16 + /// encoded sequence and copies the value(s) into the + /// `char[]` `dst`, starting at the index + /// `dstIndex`. + /// + /// #### Parameters + /// + /// - `codePoint`: The Unicode code point to encode. + /// + /// - `dst`: The `char[]` to copy the encoded value into. + /// + /// - `dstIndex`: The index to start copying into `dst`. + /// + /// #### Returns + /// + /// @return The number of `char` value units copied into + /// `dst`. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException if `codePoint` is not a + /// valid Unicode code point. + /// + /// - `NullPointerException`: if `dst` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `dstIndex` is negative, + /// greater than or equal to `dst.length` or equals + /// `dst.length - 1` when `codePoint` is a + /// `supplementary code point`. + /// + /// #### Since + /// + /// 1.5 public static int toChars(int codePoint, char[] dst, int dstIndex) { if (!isValidCodePoint(codePoint)) { throw new IllegalArgumentException(); @@ -668,21 +724,28 @@ public static int toChars(int codePoint, char[] dst, int dstIndex) { return 1; } - /** - *

- * Converts the Unicode code point, codePoint, into a UTF-16 - * encoded sequence that is returned as a char[]. - *

- * - * @param codePoint The Unicode code point to encode. - * @return The UTF-16 encoded char sequence; if code point is - * a {@link #isSupplementaryCodePoint(int) supplementary code point}, - * then a 2 char array is returned, otherwise a 1 - * char array is returned. - * @throws IllegalArgumentException if codePoint is not a - * valid Unicode code point. - * @since 1.5 - */ + /// Converts the Unicode code point, `codePoint`, into a UTF-16 + /// encoded sequence that is returned as a `char[]`. + /// + /// #### Parameters + /// + /// - `codePoint`: The Unicode code point to encode. + /// + /// #### Returns + /// + /// @return The UTF-16 encoded `char` sequence; if code point is + /// a `supplementary code point`, + /// then a 2 `char` array is returned, otherwise a 1 + /// `char` array is returned. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException if `codePoint` is not a + /// valid Unicode code point. + /// + /// #### Since + /// + /// 1.5 public static char[] toChars(int codePoint) { if (!isValidCodePoint(codePoint)) { throw new IllegalArgumentException(); @@ -697,24 +760,34 @@ public static char[] toChars(int codePoint) { return new char[] { (char) codePoint }; } - /** - *

- * Counts the number of Unicode code points in the subsequence of the - * CharSequence, as delineated by the - * beginIndex and endIndex. Any surrogate - * values with missing pair values will be counted as 1 code point. - *

- * - * @param seq The CharSequence to look through. - * @param beginIndex The inclusive index to begin counting at. - * @param endIndex The exclusive index to stop counting at. - * @return The number of Unicode code points. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if beginIndex is - * negative, greater than seq.length() or greater - * than endIndex. - * @since 1.5 - */ + /// Counts the number of Unicode code points in the subsequence of the + /// `CharSequence`, as delineated by the + /// `beginIndex` and `endIndex`. Any surrogate + /// values with missing pair values will be counted as 1 code point. + /// + /// #### Parameters + /// + /// - `seq`: The `CharSequence` to look through. + /// + /// - `beginIndex`: The inclusive index to begin counting at. + /// + /// - `endIndex`: The exclusive index to stop counting at. + /// + /// #### Returns + /// + /// The number of Unicode code points. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `beginIndex` is + /// negative, greater than `seq.length()` or greater + /// than `endIndex`. + /// + /// #### Since + /// + /// 1.5 public static int codePointCount(CharSequence seq, int beginIndex, int endIndex) { if (seq == null) { @@ -741,25 +814,35 @@ public static int codePointCount(CharSequence seq, int beginIndex, return result; } - /** - *

- * Counts the number of Unicode code points in the subsequence of the - * char[], as delineated by the offset and - * count. Any surrogate values with missing pair values will - * be counted as 1 code point. - *

- * - * @param seq The char[] to look through. - * @param offset The inclusive index to begin counting at. - * @param count The number of char values to look through in - * seq. - * @return The number of Unicode code points. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if offset or - * count is negative or if endIndex is - * greater than seq.length. - * @since 1.5 - */ + /// Counts the number of Unicode code points in the subsequence of the + /// `char[]`, as delineated by the `offset` and + /// `count`. Any surrogate values with missing pair values will + /// be counted as 1 code point. + /// + /// #### Parameters + /// + /// - `seq`: The `char[]` to look through. + /// + /// - `offset`: The inclusive index to begin counting at. + /// + /// - `count`: @param count The number of `char` values to look through in + /// `seq`. + /// + /// #### Returns + /// + /// The number of Unicode code points. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `offset` or + /// `count` is negative or if `endIndex` is + /// greater than `seq.length`. + /// + /// #### Since + /// + /// 1.5 public static int codePointCount(char[] seq, int offset, int count) { if (seq == null) { throw new NullPointerException(); @@ -786,28 +869,38 @@ public static int codePointCount(char[] seq, int offset, int count) { return result; } - /** - *

- * Determines the index into the CharSequence that is offset - * (measured in code points and specified by codePointOffset), - * from the index argument. - *

- * - * @param seq The CharSequence to find the index within. - * @param index The index to begin from, within the - * CharSequence. - * @param codePointOffset The number of code points to look back or - * forwards; may be a negative or positive value. - * @return The calculated index that is codePointOffset code - * points from index. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if index is negative, - * greater than seq.length(), there aren't enough - * values in seq after index or before - * index if codePointOffset is - * negative. - * @since 1.5 - */ + /// Determines the index into the `CharSequence` that is offset + /// (measured in code points and specified by `codePointOffset`), + /// from the `index` argument. + /// + /// #### Parameters + /// + /// - `seq`: The `CharSequence` to find the index within. + /// + /// - `index`: @param index The index to begin from, within the + /// `CharSequence`. + /// + /// - `codePointOffset`: @param codePointOffset The number of code points to look back or + /// forwards; may be a negative or positive value. + /// + /// #### Returns + /// + /// @return The calculated index that is `codePointOffset` code + /// points from `index`. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `index` is negative, + /// greater than `seq.length()`, there aren't enough + /// values in `seq` after `index` or before + /// `index` if `codePointOffset` is + /// negative. + /// + /// #### Since + /// + /// 1.5 public static int offsetByCodePoints(CharSequence seq, int index, int codePointOffset) { if (seq == null) { @@ -859,36 +952,47 @@ public static int offsetByCodePoints(CharSequence seq, int index, return i; } - /** - *

- * Determines the index into the char[] that is offset - * (measured in code points and specified by codePointOffset), - * from the index argument and is within the subsequence as - * delineated by start and count. - *

- * - * @param seq The char[] to find the index within. - * - * @param index The index to begin from, within the char[]. - * @param codePointOffset The number of code points to look back or - * forwards; may be a negative or positive value. - * @param start The inclusive index that marks the beginning of the - * subsequence. - * @param count The number of char values to include within - * the subsequence. - * @return The calculated index that is codePointOffset code - * points from index. - * @throws NullPointerException if seq is null. - * @throws IndexOutOfBoundsException if start or - * count is negative, start + count - * greater than seq.length, index is - * less than start, index is greater - * than start + count or there aren't enough values - * in seq after index or before - * index if codePointOffset is - * negative. - * @since 1.5 - */ + /// Determines the index into the `char[]` that is offset + /// (measured in code points and specified by `codePointOffset`), + /// from the `index` argument and is within the subsequence as + /// delineated by `start` and `count`. + /// + /// #### Parameters + /// + /// - `seq`: The `char[]` to find the index within. + /// + /// - `index`: The index to begin from, within the `char[]`. + /// + /// - `codePointOffset`: @param codePointOffset The number of code points to look back or + /// forwards; may be a negative or positive value. + /// + /// - `start`: @param start The inclusive index that marks the beginning of the + /// subsequence. + /// + /// - `count`: @param count The number of `char` values to include within + /// the subsequence. + /// + /// #### Returns + /// + /// @return The calculated index that is `codePointOffset` code + /// points from `index`. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `seq` is `null`. + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException if `start` or + /// `count` is negative, `start + count` + /// greater than `seq.length`, `index` is + /// less than `start`, `index` is greater + /// than `start + count` or there aren't enough values + /// in `seq` after `index` or before + /// `index` if `codePointOffset` is + /// negative. + /// + /// #### Since + /// + /// 1.5 public static int offsetByCodePoints(char[] seq, int start, int count, int index, int codePointOffset) { if (seq == null) { @@ -941,29 +1045,34 @@ public static int offsetByCodePoints(char[] seq, int start, int count, return i; } - /** - * Reverse the order of the first and second bytes in character - * @param c - * the character - * @return the character with reordered bytes. - */ + /// Reverse the order of the first and second bytes in character + /// + /// #### Parameters + /// + /// - `c`: the character + /// + /// #### Returns + /// + /// the character with reordered bytes. public static char reverseBytes(char c) { return (char)((c<<8) | (c>>8)); } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Character valueOf(char i) { return null; } - /** - * See {@link #isWhitespace(int)}. - */ + /// See `#isWhitespace(int)`. public static boolean isWhitespace(char c) { return isWhitespace((int) c); } @@ -988,13 +1097,11 @@ public static boolean isSpaceChar(char ch) { - /** - * Returns true if the given code point is a Unicode whitespace character. - * The exact set of characters considered as whitespace varies with Unicode version. - * Note that non-breaking spaces are not considered whitespace. - * Note also that line separators are considered whitespace; see {@link #isSpaceChar} - * for an alternative. - */ + /// Returns true if the given code point is a Unicode whitespace character. + /// The exact set of characters considered as whitespace varies with Unicode version. + /// Note that non-breaking spaces are not considered whitespace. + /// Note also that line separators are considered whitespace; see `#isSpaceChar` + /// for an alternative. public static boolean isWhitespace(int codePoint) { // We don't just call into icu4c because of the JNI overhead. Ideally we'd fix that. // Any ASCII whitespace character? diff --git a/Ports/CLDC11/src/java/lang/Class.java b/Ports/CLDC11/src/java/lang/Class.java index 2e640a47ab..ae8200a31c 100644 --- a/Ports/CLDC11/src/java/lang/Class.java +++ b/Ports/CLDC11/src/java/lang/Class.java @@ -26,91 +26,77 @@ import java.lang.annotation.*; import java.lang.reflect.Constructor; import java.lang.reflect.Method; -/** - * Instances of the class Class represent classes and interfaces in a running Java application. Every array also belongs to a class that is reflected as a Class object that is shared by all arrays with the same element type and number of dimensions. - * Class has no public constructor. Instead Class objects are constructed automatically by the Java Virtual Machine as classes are loaded. - * The following example uses a Class object to print the class name of an object: - * Since: JDK1.0, CLDC 1.0 - */ +/// Instances of the class Class represent classes and interfaces in a running Java application. Every array also belongs to a class that is reflected as a Class object that is shared by all arrays with the same element type and number of dimensions. +/// Class has no public constructor. Instead Class objects are constructed automatically by the Java Virtual Machine as classes are loaded. +/// The following example uses a Class object to print the class name of an object: +/// Since: JDK1.0, CLDC 1.0 public final class Class implements java.lang.reflect.Type { public ClassLoader getClassLoader() { return ClassLoader.getSystemClassLoader(); } - /** - * Returns the Class object associated with the class with the given string name. Given the fully-qualified name for a class or interface, this method attempts to locate, load and link the class. - * For example, the following code fragment returns the runtime Class descriptor for the class named java.lang.Thread: Classt= Class.forName("java.lang.Thread") - * @deprecated don't use this method for anything important since class names are obfuscated on the device! - */ + /// Returns the Class object associated with the class with the given string name. Given the fully-qualified name for a class or interface, this method attempts to locate, load and link the class. + /// For example, the following code fragment returns the runtime Class descriptor for the class named java.lang.Thread: Classt= Class.forName("java.lang.Thread") + /// + /// #### Deprecated + /// + /// don't use this method for anything important since class names are obfuscated on the device! public static java.lang.Class forName(java.lang.String className) throws java.lang.ClassNotFoundException{ return null; //TODO codavaj!! } - /** - * Returns the fully-qualified name of the entity (class, interface, array class, primitive type, or void) represented by this Class object, as a String. - * If this Class object represents a class of arrays, then the internal form of the name consists of the name of the element type in Java signature format, preceded by one or more "[" characters representing the depth of array nesting. Thus: - * (new Object[3]).getClass().getName() returns "[Ljava.lang.Object;" and: (new int[3][4][5][6][7][8][9]).getClass().getName() returns "[[[[[[[I". The encoding of element type names is as follows: B byte C char D double F float I int J long L - * class or interface S short Z boolean The class or interface name - * is given in fully qualified form as shown in the example above. - * @deprecated don't use this method for anything important since class names are obfuscated on the device! - */ + /// Returns the fully-qualified name of the entity (class, interface, array class, primitive type, or void) represented by this Class object, as a String. + /// If this Class object represents a class of arrays, then the internal form of the name consists of the name of the element type in Java signature format, preceded by one or more "[" characters representing the depth of array nesting. Thus: + /// (new Object[3]).getClass().getName() returns "[Ljava.lang.Object;" and: (new int[3][4][5][6][7][8][9]).getClass().getName() returns "[[[[[[[I". The encoding of element type names is as follows: B byte C char D double F float I int J long L + /// class or interface S short Z boolean The class or interface name + /// is given in fully qualified form as shown in the example above. + /// + /// #### Deprecated + /// + /// don't use this method for anything important since class names are obfuscated on the device! public java.lang.String getName(){ return null; //TODO codavaj!! } - /** - * Finds a resource with a given name in the application's JAR file. This method returns null if no resource with this name is found in the application's JAR file. - * The resource names can be represented in two different formats: absolute or relative. - * Absolute format: /packagePathName/resourceName - * Relative format: resourceName - * In the absolute format, the programmer provides a fully qualified name that includes both the full path and the name of the resource inside the JAR file. In the path names, the character "/" is used as the separator. - * In the relative format, the programmer provides only the name of the actual resource. Relative names are converted to absolute names by the system by prepending the resource name with the fully qualified package name of class upon which the getResourceAsStream method was called. - */ + /// Finds a resource with a given name in the application's JAR file. This method returns null if no resource with this name is found in the application's JAR file. + /// The resource names can be represented in two different formats: absolute or relative. + /// Absolute format: /packagePathName/resourceName + /// Relative format: resourceName + /// In the absolute format, the programmer provides a fully qualified name that includes both the full path and the name of the resource inside the JAR file. In the path names, the character "/" is used as the separator. + /// In the relative format, the programmer provides only the name of the actual resource. Relative names are converted to absolute names by the system by prepending the resource name with the fully qualified package name of class upon which the getResourceAsStream method was called. public java.io.InputStream getResourceAsStream(java.lang.String name){ return null; //TODO codavaj!! } - /** - * Determines if this Class object represents an array class. - */ + /// Determines if this Class object represents an array class. public boolean isArray(){ return false; //TODO codavaj!! } - /** - * Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter. It returns true if so; otherwise it returns false. If this Class object represents a primitive type, this method returns true if the specified Class parameter is exactly this Class object; otherwise it returns false. - * Specifically, this method tests whether the type represented by the specified Class parameter can be converted to the type represented by this Class object via an identity conversion or via a widening reference conversion. See The Java Language Specification, sections 5.1.1 and 5.1.4 , for details. - */ + /// Determines if the class or interface represented by this Class object is either the same as, or is a superclass or superinterface of, the class or interface represented by the specified Class parameter. It returns true if so; otherwise it returns false. If this Class object represents a primitive type, this method returns true if the specified Class parameter is exactly this Class object; otherwise it returns false. + /// Specifically, this method tests whether the type represented by the specified Class parameter can be converted to the type represented by this Class object via an identity conversion or via a widening reference conversion. See The Java Language Specification, sections 5.1.1 and 5.1.4 , for details. public boolean isAssignableFrom(java.lang.Class cls){ return false; //TODO codavaj!! } - /** - * Determines if the specified Object is assignment-compatible with the object represented by this Class. This method is the dynamic equivalent of the Java language instanceof operator. The method returns true if the specified Object argument is non-null and can be cast to the reference type represented by this Class object without raising a ClassCastException. It returns false otherwise. - * Specifically, if this Class object represents a declared class, this method returns true if the specified Object argument is an instance of the represented class (or of any of its subclasses); it returns false otherwise. If this Class object represents an array class, this method returns true if the specified Object argument can be converted to an object of the array class by an identity conversion or by a widening reference conversion; it returns false otherwise. If this Class object represents an interface, this method returns true if the class or any superclass of the specified Object argument implements this interface; it returns false otherwise. If this Class object represents a primitive type, this method returns false. - */ + /// Determines if the specified Object is assignment-compatible with the object represented by this Class. This method is the dynamic equivalent of the Java language instanceof operator. The method returns true if the specified Object argument is non-null and can be cast to the reference type represented by this Class object without raising a ClassCastException. It returns false otherwise. + /// Specifically, if this Class object represents a declared class, this method returns true if the specified Object argument is an instance of the represented class (or of any of its subclasses); it returns false otherwise. If this Class object represents an array class, this method returns true if the specified Object argument can be converted to an object of the array class by an identity conversion or by a widening reference conversion; it returns false otherwise. If this Class object represents an interface, this method returns true if the class or any superclass of the specified Object argument implements this interface; it returns false otherwise. If this Class object represents a primitive type, this method returns false. public boolean isInstance(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Determines if the specified Class object represents an interface type. - */ + /// Determines if the specified Class object represents an interface type. public boolean isInterface(){ return false; //TODO codavaj!! } - /** - * Creates a new instance of a class. - */ + /// Creates a new instance of a class. public java.lang.Object newInstance() throws java.lang.InstantiationException, java.lang.IllegalAccessException{ return null; //TODO codavaj!! } - /** - * Converts the object to a string. The string representation is the string "class" or "interface", followed by a space, and then by the fully qualified name of the class in the format returned by getName. If this Class object represents a primitive type, this method returns the name of the primitive type. If this Class object represents void this method returns "void". - */ + /// Converts the object to a string. The string representation is the string "class" or "interface", followed by a space, and then by the fully qualified name of the class in the format returned by getName. If this Class object represents a primitive type, this method returns the name of the primitive type. If this Class object represents void this method returns "void". public java.lang.String toString(){ return null; //TODO codavaj!! } @@ -121,10 +107,7 @@ public boolean isAnnotation() { return false; } - /** - * Returns this element's annotation for the specified type if such an annotation is present, else null. - * - */ + /// Returns this element's annotation for the specified type if such an annotation is present, else null. public T getAnnotation( Class annotationType ) { if ( annotationType == null ) { throw new NullPointerException( "Null annotationType" ); @@ -133,148 +116,143 @@ public T getAnnotation( Class annotationType ) { return null;//AIB.getAib(c).getClassAnnotation(annotationType); } - /** - * Returns all annotations present on this element. - */ + /// Returns all annotations present on this element. public Annotation[] getAnnotations() { return null;//AIB.getAib(c).getClassAnnotations(); } - /** - * Returns all annotations that are directly present on this element. - */ + /// Returns all annotations that are directly present on this element. public Annotation[] getDeclaredAnnotations() { return null;//AIB.getAib(c).getDeclaredClassAnnotations(); } - /** - * Returns true if an annotation for the specified type is present on this element, else false. - */ + /// Returns true if an annotation for the specified type is present on this element, else false. public boolean isAnnotationPresent( Class annotationType ) { return false; } - /** - * Replacement for Class.asSubclass(Class). - * - * @param c a Class - * @param superclass another Class which must be a superclass of c - * @return c - * @throws java.lang.ClassCastException if c is - */ + /// Replacement for Class.asSubclass(Class). + /// + /// #### Parameters + /// + /// - `c`: a Class + /// + /// - `superclass`: another Class which must be a superclass of *c* + /// + /// #### Returns + /// + /// *c* + /// + /// #### Throws + /// + /// - `java.lang.ClassCastException`: if *c* is public Class asSubclass(Class superclass) { return null; } - /** - * Replacement for Class.cast(Object). Throws a ClassCastException if obj - * is not an instance of class c, or a subtype of c. - * - * @param c Class we want to cast obj to - * @param object object we want to cast - * @return The object, or null if the object is - * null. - * @throws java.lang.ClassCastException if obj is not - * null or an instance of c - */ + /// Replacement for Class.cast(Object). Throws a ClassCastException if *obj* + /// is not an instance of class c, or a subtype of c. + /// + /// #### Parameters + /// + /// - `c`: Class we want to cast obj to + /// + /// - `object`: object we want to cast + /// + /// #### Returns + /// + /// @return The object, or `null` if the object is + /// `null`. + /// + /// #### Throws + /// + /// - `java.lang.ClassCastException`: @throws java.lang.ClassCastException if obj is not + /// `null` or an instance of c public Object cast(Object object) { return null; } - /** - * Replacement for Class.isEnum(). - * - * @param class_ class we want to test. - * @return true if the class was declared as an Enum. - */ + /// Replacement for Class.isEnum(). + /// + /// #### Parameters + /// + /// - `class_`: class we want to test. + /// + /// #### Returns + /// + /// true if the class was declared as an Enum. public boolean isEnum() { return false; } - /** - * replacement for Class.isAnonymousClass() - */ + /// replacement for Class.isAnonymousClass() public boolean isAnonymousClass() { return false; } - /** - * @deprecated don't use this method for anything important since class names are obfuscated on the device! - */ + /// #### Deprecated + /// + /// don't use this method for anything important since class names are obfuscated on the device! public String getSimpleName() { return null; } - /** - * replacement for Class.isSynthetic() - */ + /// replacement for Class.isSynthetic() public boolean isSynthetic() { return false; } - /** - * @deprecated don't use this method for anything important since class names are obfuscated on the device! - */ + /// #### Deprecated + /// + /// don't use this method for anything important since class names are obfuscated on the device! public String getCanonicalName() { return null; } - /** - * Gets for Array classes, this returns the type of the elements of the array. - * @return - */ + /// Gets for Array classes, this returns the type of the elements of the array. public Class getComponentType() { return null; } - /** - * @deprecated Not supported - * @return - */ + /// #### Deprecated + /// + /// Not supported public boolean desiredAssertionStatus() { return false; } - /** - * @deprecated Not supported - * @return - */ + /// #### Deprecated + /// + /// Not supported public java.lang.reflect.Type[] getGenericInterfaces() { throw new UnsupportedOperationException("Class.getGenericInterfaces() not supported on this platform"); } - /** - * Returns true if this class is a primitive type. - * @return - */ + /// Returns true if this class is a primitive type. public boolean isPrimitive() { return false; } - /** - * - * @return - * @deprecated Not supported - */ + /// #### Deprecated + /// + /// Not supported public Method getEnclosingMethod() { return null; } - /** - * Returns null always. Not supported in CN1. - * @return - * @deprecated Not supported - */ + /// Returns null always. Not supported in CN1. + /// + /// #### Deprecated + /// + /// Not supported public Constructor getEnclosingConstructor() { return null; } - /** - * - * @return - * @deprecated Not supported - */ + /// #### Deprecated + /// + /// Not supported public boolean isLocalClass() { return false; } diff --git a/Ports/CLDC11/src/java/lang/ClassCastException.java b/Ports/CLDC11/src/java/lang/ClassCastException.java index e7a9ddcfc2..9bbcf10634 100644 --- a/Ports/CLDC11/src/java/lang/ClassCastException.java +++ b/Ports/CLDC11/src/java/lang/ClassCastException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that the code has attempted to cast an object to a subclass of which it is not an instance. For example, the following code generates a ClassCastException: - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that the code has attempted to cast an object to a subclass of which it is not an instance. For example, the following code generates a ClassCastException: +/// Since: JDK1.0, CLDC 1.0 public class ClassCastException extends java.lang.RuntimeException{ - /** - * Constructs a ClassCastException with no detail message. - */ + /// Constructs a ClassCastException with no detail message. public ClassCastException(){ //TODO codavaj!! } - /** - * Constructs a ClassCastException with the specified detail message. - * s - the detail message. - */ + /// Constructs a ClassCastException with the specified detail message. + /// s - the detail message. public ClassCastException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/ClassNotFoundException.java b/Ports/CLDC11/src/java/lang/ClassNotFoundException.java index 85a6bd655b..567da68488 100644 --- a/Ports/CLDC11/src/java/lang/ClassNotFoundException.java +++ b/Ports/CLDC11/src/java/lang/ClassNotFoundException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown when an application tries to load in a class through its string name using the forName method in class Class but no definition for the class with the specified name could be found. - * Since: JDK1.0, CLDC 1.0 See Also:Class.forName(java.lang.String) - */ +/// Thrown when an application tries to load in a class through its string name using the forName method in class Class but no definition for the class with the specified name could be found. +/// Since: JDK1.0, CLDC 1.0 See Also:Class.forName(java.lang.String) public class ClassNotFoundException extends java.lang.Exception{ - /** - * Constructs a ClassNotFoundException with no detail message. - */ + /// Constructs a ClassNotFoundException with no detail message. public ClassNotFoundException(){ //TODO codavaj!! } - /** - * Constructs a ClassNotFoundException with the specified detail message. - * s - the detail message. - */ + /// Constructs a ClassNotFoundException with the specified detail message. + /// s - the detail message. public ClassNotFoundException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/CloneNotSupportedException.java b/Ports/CLDC11/src/java/lang/CloneNotSupportedException.java index 642d014f34..4094d95920 100644 --- a/Ports/CLDC11/src/java/lang/CloneNotSupportedException.java +++ b/Ports/CLDC11/src/java/lang/CloneNotSupportedException.java @@ -17,31 +17,28 @@ package java.lang; -/** - * Thrown when a program attempts to clone an object which does not support the - * {@link Cloneable} interface. - * - * @see Cloneable - */ +/// Thrown when a program attempts to clone an object which does not support the +/// `Cloneable` interface. +/// +/// #### See also +/// +/// - Cloneable public class CloneNotSupportedException extends Exception { private static final long serialVersionUID = 5195511250079656443L; - /** - * Constructs a new {@code CloneNotSupportedException} that includes the - * current stack trace. - */ + /// Constructs a new `CloneNotSupportedException` that includes the + /// current stack trace. public CloneNotSupportedException() { super(); } - /** - * Constructs a new {@code CloneNotSupportedException} with the current - * stack trace and the specified detail message. - * - * @param detailMessage - * the detail message for this exception. - */ + /// Constructs a new `CloneNotSupportedException` with the current + /// stack trace and the specified detail message. + /// + /// #### Parameters + /// + /// - `detailMessage`: the detail message for this exception. public CloneNotSupportedException(String detailMessage) { super(detailMessage); } diff --git a/Ports/CLDC11/src/java/lang/Cloneable.java b/Ports/CLDC11/src/java/lang/Cloneable.java index 91e1c8f30a..2df0f7c432 100644 --- a/Ports/CLDC11/src/java/lang/Cloneable.java +++ b/Ports/CLDC11/src/java/lang/Cloneable.java @@ -18,16 +18,20 @@ package java.lang; -/** - * This (empty) interface must be implemented by all classes that wish to - * support cloning. The implementation of {@code clone()} in {@code Object} - * checks if the object being cloned implements this interface and throws - * {@code CloneNotSupportedException} if it does not. - * - * @see Object#clone - * @see CloneNotSupportedException - * @deprecated clone isn't supported in Codename One, this interface is here strictly for compilation purposes - */ +/// This (empty) interface must be implemented by all classes that wish to +/// support cloning. The implementation of `clone()` in `Object` +/// checks if the object being cloned implements this interface and throws +/// `CloneNotSupportedException` if it does not. +/// +/// #### Deprecated +/// +/// clone isn't supported in Codename One, this interface is here strictly for compilation purposes +/// +/// #### See also +/// +/// - Object#clone +/// +/// - CloneNotSupportedException public interface Cloneable { // Marker interface } diff --git a/Ports/CLDC11/src/java/lang/Comparable.java b/Ports/CLDC11/src/java/lang/Comparable.java index 129685b67c..a91fa840d6 100644 --- a/Ports/CLDC11/src/java/lang/Comparable.java +++ b/Ports/CLDC11/src/java/lang/Comparable.java @@ -17,37 +17,40 @@ package java.lang; -/** - * This interface should be implemented by all classes that wish to define a - * natural order of their instances. - * {@link java.util.Collections#sort} and {@code java.util.Arrays#sort} can then - * be used to automatically sort lists of classes that implement this interface. - *

- * The order rule must be both transitive (if {@code x.compareTo(y) < 0} and - * {@code y.compareTo(z) < 0}, then {@code x.compareTo(z) < 0} must hold) and - * invertible (the sign of the result of x.compareTo(y) must be equal to the - * negation of the sign of the result of y.compareTo(x) for all combinations of - * x and y). - *

- * In addition, it is recommended (but not required) that if and only if the - * result of x.compareTo(y) is zero, then the result of x.equals(y) should be - * {@code true}. - */ +/// This interface should be implemented by all classes that wish to define a +/// *natural order* of their instances. +/// `java.util.Collections#sort` and `java.util.Arrays#sort` can then +/// be used to automatically sort lists of classes that implement this interface. +/// +/// The order rule must be both transitive (if `x.compareTo(y) < 0` and +/// `y.compareTo(z) < 0`, then `x.compareTo(z) < 0` must hold) and +/// invertible (the sign of the result of x.compareTo(y) must be equal to the +/// negation of the sign of the result of y.compareTo(x) for all combinations of +/// x and y). +/// +/// In addition, it is recommended (but not required) that if and only if the +/// result of x.compareTo(y) is zero, then the result of x.equals(y) should be +/// `true`. public interface Comparable { - /** - * Compares this object to the specified object to determine their relative - * order. - * - * @param another - * the object to compare to this instance. - * @return a negative integer if this instance is less than {@code another}; - * a positive integer if this instance is greater than - * {@code another}; 0 if this instance has the same order as - * {@code another}. - * @throws ClassCastException - * if {@code another} cannot be converted into something - * comparable to {@code this} instance. - */ + /// Compares this object to the specified object to determine their relative + /// order. + /// + /// #### Parameters + /// + /// - `another`: the object to compare to this instance. + /// + /// #### Returns + /// + /// @return a negative integer if this instance is less than `another`; + /// a positive integer if this instance is greater than + /// `another`; 0 if this instance has the same order as + /// `another`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if `another` cannot be converted into something + /// comparable to `this` instance. int compareTo(T another); } diff --git a/Ports/CLDC11/src/java/lang/Deprecated.java b/Ports/CLDC11/src/java/lang/Deprecated.java index e4cc651e35..ee0b351696 100644 --- a/Ports/CLDC11/src/java/lang/Deprecated.java +++ b/Ports/CLDC11/src/java/lang/Deprecated.java @@ -20,13 +20,11 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Documented; -/** - *

- * An annotation for marking an element as deprecated. - *

- * - * @since 1.5 - */ +/// An annotation for marking an element as deprecated. +/// +/// #### Since +/// +/// 1.5 @Documented @Retention(RetentionPolicy.RUNTIME) public @interface Deprecated { diff --git a/Ports/CLDC11/src/java/lang/Double.java b/Ports/CLDC11/src/java/lang/Double.java index c9d593aaba..cf09546371 100644 --- a/Ports/CLDC11/src/java/lang/Double.java +++ b/Ports/CLDC11/src/java/lang/Double.java @@ -22,225 +22,179 @@ * have any questions. */ package java.lang; -/** - * The Double class wraps a value of the primitive type double in an object. An object of type Double contains a single field whose type is double. - * In addition, this class provides several methods for converting a double to a String and a String to a double, as well as other constants and methods useful when dealing with a double. - * Since: JDK1.0, CLDC 1.1 - */ +/// The Double class wraps a value of the primitive type double in an object. An object of type Double contains a single field whose type is double. +/// In addition, this class provides several methods for converting a double to a String and a String to a double, as well as other constants and methods useful when dealing with a double. +/// Since: JDK1.0, CLDC 1.1 public final class Double extends Number implements Comparable { public static final Class TYPE = double.class; - /** - * The largest positive finite value of type double. It is equal to the value returned by Double.longBitsToDouble(0x7fefffffffffffffL) - * See Also:Constant Field Values - */ + /// The largest positive finite value of type double. It is equal to the value returned by Double.longBitsToDouble(0x7fefffffffffffffL) + /// See Also:Constant Field Values public static final double MAX_VALUE=1.7976931348623157E308d; - /** - * The smallest positive value of type double. It is equal to the value returned by Double.longBitsToDouble(0x1L). - */ + /// The smallest positive value of type double. It is equal to the value returned by Double.longBitsToDouble(0x1L). public static final double MIN_VALUE=0.0d; - /** - * A Not-a-Number (NaN) value of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff8000000000000L). - * See Also:Constant Field Values - */ + /// A Not-a-Number (NaN) value of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff8000000000000L). + /// See Also:Constant Field Values public static final double NaN=0d/0d; - /** - * The negative infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0xfff0000000000000L). - * See Also:Constant Field Values - */ + /// The negative infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0xfff0000000000000L). + /// See Also:Constant Field Values public static final double NEGATIVE_INFINITY=-1d/0d; - /** - * The positive infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff0000000000000L). - * See Also:Constant Field Values - */ + /// The positive infinity of type double. It is equal to the value returned by Double.longBitsToDouble(0x7ff0000000000000L). + /// See Also:Constant Field Values public static final double POSITIVE_INFINITY=1d/0d; - /** - * Constructs a newly allocated Double object that represents the primitive double argument. - * value - the value to be represented by the Double. - */ + /// Constructs a newly allocated Double object that represents the primitive double argument. + /// value - the value to be represented by the Double. public Double(double value){ //TODO codavaj!! } - /** - * Returns the value of this Double as a byte (by casting to a byte). - */ + /// Returns the value of this Double as a byte (by casting to a byte). public byte byteValue(){ return 0; //TODO codavaj!! } - /** - * Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout. - * Bit 63 (the bit that is selected by the mask 0x8000000000000000L) represents the sign of the floating-point number. Bits 62-52 (the bits that are selected by the mask 0x7ff0000000000000L) represent the exponent. Bits 51-0 (the bits that are selected by the mask 0x000fffffffffffffL) represent the significand (sometimes called the mantissa) of the floating-point number. - * If the argument is positive infinity, the result is 0x7ff0000000000000L. - * If the argument is negative infinity, the result is 0xfff0000000000000L. - * If the argument is NaN, the result is 0x7ff8000000000000L. - * In all cases, the result is a long integer that, when given to the longBitsToDouble(long) method, will produce a floating-point value equal to the argument to doubleToLongBits. - */ + /// Returns a representation of the specified floating-point value according to the IEEE 754 floating-point "double format" bit layout. + /// Bit 63 (the bit that is selected by the mask 0x8000000000000000L) represents the sign of the floating-point number. Bits 62-52 (the bits that are selected by the mask 0x7ff0000000000000L) represent the exponent. Bits 51-0 (the bits that are selected by the mask 0x000fffffffffffffL) represent the significand (sometimes called the mantissa) of the floating-point number. + /// If the argument is positive infinity, the result is 0x7ff0000000000000L. + /// If the argument is negative infinity, the result is 0xfff0000000000000L. + /// If the argument is NaN, the result is 0x7ff8000000000000L. + /// In all cases, the result is a long integer that, when given to the longBitsToDouble(long) method, will produce a floating-point value equal to the argument to doubleToLongBits. public static long doubleToLongBits(double value){ return 0l; //TODO codavaj!! } - /** - * Returns the double value of this Double. - */ + /// Returns the double value of this Double. public double doubleValue(){ return 0.0d; //TODO codavaj!! } - /** - * Compares this object against the specified object. The result is true if and only if the argument is not null and is a Double object that represents a double that has the identical bit pattern to the bit pattern of the double represented by this object. For this purpose, two double values are considered to be the same if and only if the method - * returns the same long value when applied to each. - * Note that in most cases, for two instances of class Double, d1 and d2, the value of d1.equals(d2) is true if and only if - * d1.doubleValue() - * == d2.doubleValue() - * also has the value true. However, there are two exceptions: If d1 and d2 both represent Double.NaN, then the equals method returns true, even though Double.NaN==Double.NaN has the value false. If d1 represents +0.0 while d2 represents -0.0, or vice versa, the equals test has the value false, even though +0.0==-0.0 has the value true. This allows hashtables to operate properly. - */ + /// Compares this object against the specified object. The result is true if and only if the argument is not null and is a Double object that represents a double that has the identical bit pattern to the bit pattern of the double represented by this object. For this purpose, two double values are considered to be the same if and only if the method + /// returns the same long value when applied to each. + /// Note that in most cases, for two instances of class Double, d1 and d2, the value of d1.equals(d2) is true if and only if + /// d1.doubleValue() + /// == d2.doubleValue() + /// also has the value true. However, there are two exceptions: If d1 and d2 both represent Double.NaN, then the equals method returns true, even though Double.NaN==Double.NaN has the value false. If d1 represents +0.0 while d2 represents -0.0, or vice versa, the equals test has the value false, even though +0.0==-0.0 has the value true. This allows hashtables to operate properly. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the float value of this Double. - */ + /// Returns the float value of this Double. public float floatValue(){ return 0.0f; //TODO codavaj!! } - /** - * Returns a hashcode for this Double object. The result is the exclusive OR of the two halves of the long integer bit representation, exactly as produced by the method - * , of the primitive double value represented by this Double object. That is, the hashcode is the value of the expression: (int)(v^(v>>>32)) where v is defined by: long v = Double.doubleToLongBits(this.doubleValue()); - */ + /// Returns a hashcode for this Double object. The result is the exclusive OR of the two halves of the long integer bit representation, exactly as produced by the method + /// , of the primitive double value represented by this Double object. That is, the hashcode is the value of the expression: (int)(v^(v>>>32)) where v is defined by: long v = Double.doubleToLongBits(this.doubleValue()); public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns the integer value of this Double (by casting to an int). - */ + /// Returns the integer value of this Double (by casting to an int). public int intValue(){ return 0; //TODO codavaj!! } - /** - * Returns true if this Double value is infinitely large in magnitude. - */ + /// Returns true if this Double value is infinitely large in magnitude. public boolean isInfinite(){ return false; //TODO codavaj!! } - /** - * Returns true if the specified number is infinitely large in magnitude. - */ + /// Returns true if the specified number is infinitely large in magnitude. public static boolean isInfinite(double v){ return false; //TODO codavaj!! } - /** - * Returns true if this Double value is the special Not-a-Number (NaN) value. - */ + /// Returns true if this Double value is the special Not-a-Number (NaN) value. public boolean isNaN(){ return false; //TODO codavaj!! } - /** - * Returns true if the specified number is the special Not-a-Number (NaN) value. - */ + /// Returns true if the specified number is the special Not-a-Number (NaN) value. public static boolean isNaN(double v){ return false; //TODO codavaj!! } - /** - * Returns the double-float corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double precision" bit layout. That floating-point value is returned as the result. - * If the argument is 0x7ff0000000000000L, the result is positive infinity. - * If the argument is 0xfff0000000000000L, the result is negative infinity. - * If the argument is any value in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL, the result is NaN. All IEEE 754 NaN values of type double are, in effect, lumped together by the Java programming language into a single value called NaN. - * In all other cases, let s, e, and m be three values that can be computed from the argument: - * int s = ((bits >> 63) == 0) ? 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) ? (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L; Then the floating-point result equals the value of the mathematical expression - * 2e-1075. - */ + /// Returns the double-float corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "double precision" bit layout. That floating-point value is returned as the result. + /// If the argument is 0x7ff0000000000000L, the result is positive infinity. + /// If the argument is 0xfff0000000000000L, the result is negative infinity. + /// If the argument is any value in the range 0x7ff0000000000001L through 0x7fffffffffffffffL or in the range 0xfff0000000000001L through 0xffffffffffffffffL, the result is NaN. All IEEE 754 NaN values of type double are, in effect, lumped together by the Java programming language into a single value called NaN. + /// In all other cases, let s, e, and m be three values that can be computed from the argument: + /// int s = ((bits >> 63) == 0) ? 1 : -1; int e = (int)((bits >> 52) & 0x7ffL); long m = (e == 0) ? (bits & 0xfffffffffffffL) << 1 : (bits & 0xfffffffffffffL) | 0x10000000000000L; Then the floating-point result equals the value of the mathematical expression + /// 2e-1075. public static double longBitsToDouble(long bits){ return 0.0d; //TODO codavaj!! } - /** - * Returns the long value of this Double (by casting to a long). - */ + /// Returns the long value of this Double (by casting to a long). public long longValue(){ return 0l; //TODO codavaj!! } - /** - * Returns a new double initialized to the value represented by the specified String, as performed by the valueOf method of class Double. - */ + /// Returns a new double initialized to the value represented by the specified String, as performed by the valueOf method of class Double. public static double parseDouble(java.lang.String s) throws java.lang.NumberFormatException{ return 0.0d; //TODO codavaj!! } - /** - * Returns the value of this Double as a short (by casting to a short). - */ + /// Returns the value of this Double as a short (by casting to a short). public short shortValue(){ return 0; //TODO codavaj!! } - /** - * Returns a String representation of this Double object. The primitive double value represented by this object is converted to a string exactly as if by the method toString of one argument. - */ + /// Returns a String representation of this Double object. The primitive double value represented by this object is converted to a string exactly as if by the method toString of one argument. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Creates a string representation of the double argument. All characters mentioned below are ASCII characters. If the argument is NaN, the result is the string "NaN". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('-'); if the sign is positive, no sign character appears in the result. As for the magnitude - * : If - * is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity". If - * is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0". If - * is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of - * , in decimal form with no leading zeroes, followed by '.' (.), followed by one or more decimal digits representing the fractional part of - * . If - * is less than 10-3 or not less than 107, then it is represented in so-called "computerized scientific notation." Let - * be the unique integer such that 10n - * = - * 10n+1; then let - * be the mathematically exact quotient of - * and 10n so that 1 - * = - * 10. The magnitude is then represented as the integer part of - * , as a single decimal digit, followed by '.' (.), followed by decimal digits representing the fractional part of - * , followed by the letter 'E' (E), followed by a representation of - * as a decimal integer, as produced by the method - * . - * How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type double. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument d. Then d must be the double value nearest to x; or if two double values are equally close to x, then d must be one of them and the least significant bit of the significand of d must be 0. - */ + /// Creates a string representation of the double argument. All characters mentioned below are ASCII characters. If the argument is NaN, the result is the string "NaN". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('-'); if the sign is positive, no sign character appears in the result. As for the magnitude + /// : If + /// is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity". If + /// is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0". If + /// is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of + /// , in decimal form with no leading zeroes, followed by '.' (.), followed by one or more decimal digits representing the fractional part of + /// . If + /// is less than 10-3 or not less than 107, then it is represented in so-called "computerized scientific notation." Let + /// be the unique integer such that 10n + /// = + /// 10n+1; then let + /// be the mathematically exact quotient of + /// and 10n so that 1 + /// = + /// 10. The magnitude is then represented as the integer part of + /// , as a single decimal digit, followed by '.' (.), followed by decimal digits representing the fractional part of + /// , followed by the letter 'E' (E), followed by a representation of + /// as a decimal integer, as produced by the method + /// . + /// How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type double. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument d. Then d must be the double value nearest to x; or if two double values are equally close to x, then d must be one of them and the least significant bit of the significand of d must be 0. public static java.lang.String toString(double d){ return null; //TODO codavaj!! } - /** - * Returns a new Double object initialized to the value represented by the specified string. The string s is interpreted as the representation of a floating-point value and a Double object representing that value is created and returned. - * If s is null, then a NullPointerException is thrown. - * Leading and trailing whitespace characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical rule: - * where - * and - * are as defined in Section 3.10.2 of the - * . If it does not have the form of a - * , then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type double by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. Finally, a new object of class Double is created to represent the double value. - */ + /// Returns a new Double object initialized to the value represented by the specified string. The string s is interpreted as the representation of a floating-point value and a Double object representing that value is created and returned. + /// If s is null, then a NullPointerException is thrown. + /// Leading and trailing whitespace characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical rule: + /// where + /// and + /// are as defined in Section 3.10.2 of the + /// . If it does not have the form of a + /// , then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type double by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. Finally, a new object of class Double is created to represent the double value. public static java.lang.Double valueOf(java.lang.String s) throws java.lang.NumberFormatException{ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Double valueOf(double i) { return null; } diff --git a/Ports/CLDC11/src/java/lang/Enum.java b/Ports/CLDC11/src/java/lang/Enum.java index db1ba5a5fe..e1592bdb30 100644 --- a/Ports/CLDC11/src/java/lang/Enum.java +++ b/Ports/CLDC11/src/java/lang/Enum.java @@ -23,11 +23,9 @@ */ package java.lang; -/** - * Implementation class required to compile enums - * - * @author Shai Almog - */ +/// Implementation class required to compile enums +/// +/// @author Shai Almog public class Enum> implements Comparable { protected Enum(final String name, final int ordinal) { diff --git a/Ports/CLDC11/src/java/lang/Error.java b/Ports/CLDC11/src/java/lang/Error.java index 3271673f3a..c9bcb82c89 100644 --- a/Ports/CLDC11/src/java/lang/Error.java +++ b/Ports/CLDC11/src/java/lang/Error.java @@ -22,23 +22,17 @@ * have any questions. */ package java.lang; -/** - * An Error is a subclass of Throwable that indicates serious problems that a reasonable application should not try to catch. Most such errors are abnormal conditions. - * A method is not required to declare in its throws clause any subclasses of Error that might be thrown during the execution of the method but not caught, since these errors are abnormal conditions that should never occur. - * Since: JDK1.0, CLDC 1.0 - */ +/// An Error is a subclass of Throwable that indicates serious problems that a reasonable application should not try to catch. Most such errors are abnormal conditions. +/// A method is not required to declare in its throws clause any subclasses of Error that might be thrown during the execution of the method but not caught, since these errors are abnormal conditions that should never occur. +/// Since: JDK1.0, CLDC 1.0 public class Error extends java.lang.Throwable{ - /** - * Constructs an Error with no specified detail message. - */ + /// Constructs an Error with no specified detail message. public Error(){ //TODO codavaj!! } - /** - * Constructs an Error with the specified detail message. - * s - the detail message. - */ + /// Constructs an Error with the specified detail message. + /// s - the detail message. public Error(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Exception.java b/Ports/CLDC11/src/java/lang/Exception.java index aa8e870b6f..b7e4eb030e 100644 --- a/Ports/CLDC11/src/java/lang/Exception.java +++ b/Ports/CLDC11/src/java/lang/Exception.java @@ -22,39 +22,36 @@ * have any questions. */ package java.lang; -/** - * The class Exception and its subclasses are a form of Throwable that indicates conditions that a reasonable application might want to catch. - * Since: JDK1.0, CLDC 1.0 See Also:Error - */ +/// The class Exception and its subclasses are a form of Throwable that indicates conditions that a reasonable application might want to catch. +/// Since: JDK1.0, CLDC 1.0 See Also:Error public class Exception extends java.lang.Throwable{ - /** - * Constructs an Exception with no specified detail message. - */ + /// Constructs an Exception with no specified detail message. public Exception(){ //TODO codavaj!! } - /** - * Constructs an Exception with the specified detail message. - * s - the detail message. - */ + /// Constructs an Exception with the specified detail message. + /// s - the detail message. public Exception(java.lang.String s){ //TODO codavaj!! } - /** - * Constructs a new exception with the provided cause. - * @param cause The cause of the exception. - */ + /// Constructs a new exception with the provided cause. + /// + /// #### Parameters + /// + /// - `cause`: The cause of the exception. public Exception(Throwable cause) { //TODO codavaj!! } - /** - * Constructs a new exception with message and cause. - * @param s The detail message. - * @param cause The cause of the exception - */ + /// Constructs a new exception with message and cause. + /// + /// #### Parameters + /// + /// - `s`: The detail message. + /// + /// - `cause`: The cause of the exception public Exception(java.lang.String s, Throwable cause) { //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Float.java b/Ports/CLDC11/src/java/lang/Float.java index 4ccd556284..723dcbf780 100644 --- a/Ports/CLDC11/src/java/lang/Float.java +++ b/Ports/CLDC11/src/java/lang/Float.java @@ -22,213 +22,165 @@ * have any questions. */ package java.lang; -/** - * The Float class wraps a value of primitive type float in an object. An object of type Float contains a single field whose type is float. - * In addition, this class provides several methods for converting a float to a String and a String to a float, as well as other constants and methods useful when dealing with a float. - * Since: JDK1.0, CLDC 1.1 - */ +/// The Float class wraps a value of primitive type float in an object. An object of type Float contains a single field whose type is float. +/// In addition, this class provides several methods for converting a float to a String and a String to a float, as well as other constants and methods useful when dealing with a float. +/// Since: JDK1.0, CLDC 1.1 public final class Float extends Number implements Comparable { - /** - * The largest positive value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f7fffff). - * See Also:Constant Field Values - */ + /// The largest positive value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f7fffff). + /// See Also:Constant Field Values public static final float MAX_VALUE=3.4028235E38f; - /** - * The smallest positive value of type float. It is equal to the value returned by Float.intBitsToFloat(0x1). - * See Also:Constant Field Values - */ + /// The smallest positive value of type float. It is equal to the value returned by Float.intBitsToFloat(0x1). + /// See Also:Constant Field Values public static final float MIN_VALUE=1.4E-45f; - /** - * The Not-a-Number (NaN) value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7fc00000). - * See Also:Constant Field Values - */ + /// The Not-a-Number (NaN) value of type float. It is equal to the value returned by Float.intBitsToFloat(0x7fc00000). + /// See Also:Constant Field Values public static final float NaN=0f/0f; - /** - * The negative infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0xff800000). - * See Also:Constant Field Values - */ + /// The negative infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0xff800000). + /// See Also:Constant Field Values public static final float NEGATIVE_INFINITY=-1f/0f; - /** - * The positive infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f800000). - * See Also:Constant Field Values - */ + /// The positive infinity of type float. It is equal to the value returned by Float.intBitsToFloat(0x7f800000). + /// See Also:Constant Field Values public static final float POSITIVE_INFINITY=1f/0f; - /** - * Constructs a newly allocated Floatobject that represents the argument converted to type float. - * value - the value to be represented by the Float. - */ + /// Constructs a newly allocated Floatobject that represents the argument converted to type float. + /// value - the value to be represented by the Float. public Float(double value){ //TODO codavaj!! } - /** - * Constructs a newly allocated Float object that represents the primitive float argument. - * value - the value to be represented by the Float. - */ + /// Constructs a newly allocated Float object that represents the primitive float argument. + /// value - the value to be represented by the Float. public Float(float value){ //TODO codavaj!! } - /** - * Returns the value of this Float as a byte (by casting to a byte). - */ + /// Returns the value of this Float as a byte (by casting to a byte). public byte byteValue(){ return 0; //TODO codavaj!! } - /** - * Returns the double value of this Float object. - */ + /// Returns the double value of this Float object. public double doubleValue(){ return 0.0d; //TODO codavaj!! } - /** - * Compares this object against some other object. The result is true if and only if the argument is not null and is a Float object that represents a float that has the identical bit pattern to the bit pattern of the float represented by this object. For this purpose, two float values are considered to be the same if and only if the method - * returns the same int value when applied to each. - * Note that in most cases, for two instances of class Float, f1 and f2, the value of f1.equals(f2) is true if and only if - * f1.floatValue() == f2.floatValue() - * also has the value true. However, there are two exceptions: If f1 and f2 both represent Float.NaN, then the equals method returns true, even though Float.NaN==Float.NaN has the value false. If f1 represents +0.0f while f2 represents -0.0f, or vice versa, the equal test has the value false, even though 0.0f==-0.0f has the value true. This definition allows hashtables to operate properly. - */ + /// Compares this object against some other object. The result is true if and only if the argument is not null and is a Float object that represents a float that has the identical bit pattern to the bit pattern of the float represented by this object. For this purpose, two float values are considered to be the same if and only if the method + /// returns the same int value when applied to each. + /// Note that in most cases, for two instances of class Float, f1 and f2, the value of f1.equals(f2) is true if and only if + /// f1.floatValue() == f2.floatValue() + /// also has the value true. However, there are two exceptions: If f1 and f2 both represent Float.NaN, then the equals method returns true, even though Float.NaN==Float.NaN has the value false. If f1 represents +0.0f while f2 represents -0.0f, or vice versa, the equal test has the value false, even though 0.0f==-0.0f has the value true. This definition allows hashtables to operate properly. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the bit representation of a single-float value. The result is a representation of the floating-point argument according to the IEEE 754 floating-point "single precision" bit layout. Bit 31 (the bit that is selected by the mask 0x80000000) represents the sign of the floating-point number. Bits 30-23 (the bits that are selected by the mask 0x7f800000) represent the exponent. Bits 22-0 (the bits that are selected by the mask 0x007fffff) represent the significand (sometimes called the mantissa) of the floating-point number. If the argument is positive infinity, the result is 0x7f800000. If the argument is negative infinity, the result is 0xff800000. If the argument is NaN, the result is 0x7fc00000. In all cases, the result is an integer that, when given to the - * method, will produce a floating-point value equal to the argument to floatToIntBits. - */ + /// Returns the bit representation of a single-float value. The result is a representation of the floating-point argument according to the IEEE 754 floating-point "single precision" bit layout. Bit 31 (the bit that is selected by the mask 0x80000000) represents the sign of the floating-point number. Bits 30-23 (the bits that are selected by the mask 0x7f800000) represent the exponent. Bits 22-0 (the bits that are selected by the mask 0x007fffff) represent the significand (sometimes called the mantissa) of the floating-point number. If the argument is positive infinity, the result is 0x7f800000. If the argument is negative infinity, the result is 0xff800000. If the argument is NaN, the result is 0x7fc00000. In all cases, the result is an integer that, when given to the + /// method, will produce a floating-point value equal to the argument to floatToIntBits. public static int floatToIntBits(float value){ return 0; //TODO codavaj!! } - /** - * Returns the float value of this Float object. - */ + /// Returns the float value of this Float object. public float floatValue(){ return 0.0f; //TODO codavaj!! } - /** - * Returns a hashcode for this Float object. The result is the integer bit representation, exactly as produced by the method - * , of the primitive float value represented by this Float object. - */ + /// Returns a hashcode for this Float object. The result is the integer bit representation, exactly as produced by the method + /// , of the primitive float value represented by this Float object. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns the single-float corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "single precision" bit layout. - * If the argument is 0x7f800000, the result is positive infinity. - * If the argument is 0xff800000, the result is negative infinity. - * If the argument is any value in the range 0x7f800001 through 0x7fffffff or in the range 0xff800001 through 0xffffffff, the result is NaN. All IEEE 754 NaN values of type float are, in effect, lumped together by the Java programming language into a single float value called NaN. - * In all other cases, let s, e, and m be three values that can be computed from the argument: - * int s = ((bits >> 31) == 0) ? 1 : -1; int e = ((bits >> 23) & 0xff); int m = (e == 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000; Then the floating-point result equals the value of the mathematical expression - * . - */ + /// Returns the single-float corresponding to a given bit representation. The argument is considered to be a representation of a floating-point value according to the IEEE 754 floating-point "single precision" bit layout. + /// If the argument is 0x7f800000, the result is positive infinity. + /// If the argument is 0xff800000, the result is negative infinity. + /// If the argument is any value in the range 0x7f800001 through 0x7fffffff or in the range 0xff800001 through 0xffffffff, the result is NaN. All IEEE 754 NaN values of type float are, in effect, lumped together by the Java programming language into a single float value called NaN. + /// In all other cases, let s, e, and m be three values that can be computed from the argument: + /// int s = ((bits >> 31) == 0) ? 1 : -1; int e = ((bits >> 23) & 0xff); int m = (e == 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000; Then the floating-point result equals the value of the mathematical expression + /// . public static float intBitsToFloat(int bits){ return 0.0f; //TODO codavaj!! } - /** - * Returns the integer value of this Float (by casting to an int). - */ + /// Returns the integer value of this Float (by casting to an int). public int intValue(){ return 0; //TODO codavaj!! } - /** - * Returns true if this Float value is infinitely large in magnitude. - */ + /// Returns true if this Float value is infinitely large in magnitude. public boolean isInfinite(){ return false; //TODO codavaj!! } - /** - * Returns true if the specified number is infinitely large in magnitude. - */ + /// Returns true if the specified number is infinitely large in magnitude. public static boolean isInfinite(float v){ return false; //TODO codavaj!! } - /** - * Returns true if this Float value is Not-a-Number (NaN). - */ + /// Returns true if this Float value is Not-a-Number (NaN). public boolean isNaN(){ return false; //TODO codavaj!! } - /** - * Returns true if the specified number is the special Not-a-Number (NaN) value. - */ + /// Returns true if the specified number is the special Not-a-Number (NaN) value. public static boolean isNaN(float v){ return false; //TODO codavaj!! } - /** - * Returns the long value of this Float (by casting to a long). - */ + /// Returns the long value of this Float (by casting to a long). public long longValue(){ return 0l; //TODO codavaj!! } - /** - * Returns a new float initialized to the value represented by the specified String. - */ + /// Returns a new float initialized to the value represented by the specified String. public static float parseFloat(java.lang.String s) throws java.lang.NumberFormatException{ return 0.0f; //TODO codavaj!! } - /** - * Returns the value of this Float as a short (by casting to a short). - */ + /// Returns the value of this Float as a short (by casting to a short). public short shortValue(){ return 0; //TODO codavaj!! } - /** - * Returns a String representation of this Float object. The primitive float value represented by this object is converted to a String exactly as if by the method toString of one argument. - */ + /// Returns a String representation of this Float object. The primitive float value represented by this object is converted to a String exactly as if by the method toString of one argument. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns a String representation for the specified float value. The argument is converted to a readable string format as follows. All characters and characters in strings mentioned below are ASCII characters. If the argument is NaN, the result is the string "NaN". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('-'); if the sign is positive, no sign character appears in the result. As for the magnitude m: If m is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity". If m is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0". If m is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of m, in decimal form with no leading zeroes, followed by '.' (.), followed by one or more decimal digits representing the fractional part of m. If m is less than 10-3 or not less than 107, then it is represented in so-called "computerized scientific notation." Let n be the unique integer such that 10n - * =m - * 1; then let a be the mathematically exact quotient of m and 10n so that 1 - * a < 10. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by '.' (.), followed by decimal digits representing the fractional part of a, followed by the letter 'E' (E), followed by a representation of n as a decimal integer, as produced by the method - * of one argument. How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type float. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument f. Then f must be the float value nearest to x; or, if two float values are equally close to xthen f must be one of them and the least significant bit of the significand of f must be 0. - */ + /// Returns a String representation for the specified float value. The argument is converted to a readable string format as follows. All characters and characters in strings mentioned below are ASCII characters. If the argument is NaN, the result is the string "NaN". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is '-' ('-'); if the sign is positive, no sign character appears in the result. As for the magnitude m: If m is infinity, it is represented by the characters "Infinity"; thus, positive infinity produces the result "Infinity" and negative infinity produces the result "-Infinity". If m is zero, it is represented by the characters "0.0"; thus, negative zero produces the result "-0.0" and positive zero produces the result "0.0". If m is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of m, in decimal form with no leading zeroes, followed by '.' (.), followed by one or more decimal digits representing the fractional part of m. If m is less than 10-3 or not less than 107, then it is represented in so-called "computerized scientific notation." Let n be the unique integer such that 10n + /// =m + /// 1; then let a be the mathematically exact quotient of m and 10n so that 1 + /// a < 10. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by '.' (.), followed by decimal digits representing the fractional part of a, followed by the letter 'E' (E), followed by a representation of n as a decimal integer, as produced by the method + /// of one argument. How many digits must be printed for the fractional part of m or a? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type float. That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument f. Then f must be the float value nearest to x; or, if two float values are equally close to xthen f must be one of them and the least significant bit of the significand of f must be 0. public static java.lang.String toString(float f){ return null; //TODO codavaj!! } - /** - * Returns the floating point value represented by the specified String. The string s is interpreted as the representation of a floating-point value and a Float object representing that value is created and returned. - * If s is null, then a NullPointerException is thrown. - * Leading and trailing whitespace characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical syntax rules: - * where - * , - * are as defined in Section 3.10.2 of the - * . If it does not have the form of a - * , then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type float by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. - */ + /// Returns the floating point value represented by the specified String. The string s is interpreted as the representation of a floating-point value and a Float object representing that value is created and returned. + /// If s is null, then a NullPointerException is thrown. + /// Leading and trailing whitespace characters in s are ignored. The rest of s should constitute a FloatValue as described by the lexical syntax rules: + /// where + /// , + /// are as defined in Section 3.10.2 of the + /// . If it does not have the form of a + /// , then a NumberFormatException is thrown. Otherwise, it is regarded as representing an exact decimal value in the usual "computerized scientific notation"; this exact decimal value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type float by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic. public static java.lang.Float valueOf(java.lang.String s) throws java.lang.NumberFormatException{ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Float valueOf(float i) { return null; } diff --git a/Ports/CLDC11/src/java/lang/IllegalAccessException.java b/Ports/CLDC11/src/java/lang/IllegalAccessException.java index 4b7d0043ed..c5fe759e5b 100644 --- a/Ports/CLDC11/src/java/lang/IllegalAccessException.java +++ b/Ports/CLDC11/src/java/lang/IllegalAccessException.java @@ -22,23 +22,17 @@ * have any questions. */ package java.lang; -/** - * Thrown when an application tries to load in a class, but the currently executing method does not have access to the definition of the specified class, because the class is not public and in another package. - * An instance of this class can also be thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the current method does not have access to the appropriate zero-argument constructor. - * Since: JDK1.0, CLDC 1.0 See Also:Class.forName(java.lang.String), Class.newInstance() - */ +/// Thrown when an application tries to load in a class, but the currently executing method does not have access to the definition of the specified class, because the class is not public and in another package. +/// An instance of this class can also be thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the current method does not have access to the appropriate zero-argument constructor. +/// Since: JDK1.0, CLDC 1.0 See Also:Class.forName(java.lang.String), Class.newInstance() public class IllegalAccessException extends java.lang.Exception{ - /** - * Constructs an IllegalAccessException without a detail message. - */ + /// Constructs an IllegalAccessException without a detail message. public IllegalAccessException(){ //TODO codavaj!! } - /** - * Constructs an IllegalAccessException with a detail message. - * s - the detail message. - */ + /// Constructs an IllegalAccessException with a detail message. + /// s - the detail message. public IllegalAccessException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/IllegalArgumentException.java b/Ports/CLDC11/src/java/lang/IllegalArgumentException.java index 57cc86cc5b..4fef902272 100644 --- a/Ports/CLDC11/src/java/lang/IllegalArgumentException.java +++ b/Ports/CLDC11/src/java/lang/IllegalArgumentException.java @@ -22,39 +22,29 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that a method has been passed an illegal or inappropriate argument. - * Since: JDK1.0, CLDC 1.0 See Also:Thread.setPriority(int) - */ +/// Thrown to indicate that a method has been passed an illegal or inappropriate argument. +/// Since: JDK1.0, CLDC 1.0 See Also:Thread.setPriority(int) public class IllegalArgumentException extends java.lang.RuntimeException{ - /** - * Constructs an IllegalArgumentException with no detail message. - */ + /// Constructs an IllegalArgumentException with no detail message. public IllegalArgumentException(){ //TODO codavaj!! } - /** - * Constructs an IllegalArgumentException with the specified detail message. - * s - the detail message. - */ + /// Constructs an IllegalArgumentException with the specified detail message. + /// s - the detail message. public IllegalArgumentException(java.lang.String s){ //TODO codavaj!! } - /** - * Constructs an IllegalArgumentException with the specified detail message and cause. - * s - the detail message. - * cause - the cause. - */ + /// Constructs an IllegalArgumentException with the specified detail message and cause. + /// s - the detail message. + /// cause - the cause. public IllegalArgumentException(java.lang.String s, java.lang.Throwable cause) { //TODO codavaj!! } - /** - * Constructs an IllegalArgumentException with the specified cause. - * cause - the cause. - */ + /// Constructs an IllegalArgumentException with the specified cause. + /// cause - the cause. public IllegalArgumentException(java.lang.Throwable cause) { //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/IllegalMonitorStateException.java b/Ports/CLDC11/src/java/lang/IllegalMonitorStateException.java index 59b6dddaae..8fb5d586c8 100644 --- a/Ports/CLDC11/src/java/lang/IllegalMonitorStateException.java +++ b/Ports/CLDC11/src/java/lang/IllegalMonitorStateException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that a thread has attempted to wait on an object's monitor or to notify other threads waiting on an object's monitor without owning the specified monitor. - * Since: JDK1.0, CLDC 1.0 See Also:Object.notify(), Object.notifyAll(), Object.wait(), Object.wait(long), Object.wait(long, int) - */ +/// Thrown to indicate that a thread has attempted to wait on an object's monitor or to notify other threads waiting on an object's monitor without owning the specified monitor. +/// Since: JDK1.0, CLDC 1.0 See Also:Object.notify(), Object.notifyAll(), Object.wait(), Object.wait(long), Object.wait(long, int) public class IllegalMonitorStateException extends java.lang.RuntimeException{ - /** - * Constructs an IllegalMonitorStateException with no detail message. - */ + /// Constructs an IllegalMonitorStateException with no detail message. public IllegalMonitorStateException(){ //TODO codavaj!! } - /** - * Constructs an IllegalMonitorStateException with the specified detail message. - * s - the detail message. - */ + /// Constructs an IllegalMonitorStateException with the specified detail message. + /// s - the detail message. public IllegalMonitorStateException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/IllegalStateException.java b/Ports/CLDC11/src/java/lang/IllegalStateException.java index 1d937141bf..e08b65551a 100644 --- a/Ports/CLDC11/src/java/lang/IllegalStateException.java +++ b/Ports/CLDC11/src/java/lang/IllegalStateException.java @@ -23,24 +23,17 @@ */ package java.lang; -/** - * - * @author user2 - */ +/// @author user2 public class IllegalStateException extends RuntimeException { public IllegalStateException() {} public IllegalStateException(String s) {} - /** - * Constructs an IllegalStateException with the specified detail message and cause. - * s - the detail message. - * cause - the cause. - */ + /// Constructs an IllegalStateException with the specified detail message and cause. + /// s - the detail message. + /// cause - the cause. public IllegalStateException(String s, Throwable cause) {} - /** - * Constructs an IllegalStateException with the specified cause. - * cause - the cause. - */ + /// Constructs an IllegalStateException with the specified cause. + /// cause - the cause. public IllegalStateException(Throwable cause) {} } diff --git a/Ports/CLDC11/src/java/lang/IllegalThreadStateException.java b/Ports/CLDC11/src/java/lang/IllegalThreadStateException.java index 79d9c34a07..22decc9ffd 100644 --- a/Ports/CLDC11/src/java/lang/IllegalThreadStateException.java +++ b/Ports/CLDC11/src/java/lang/IllegalThreadStateException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that a thread is not in an appropriate state for the requested operation. See, for example, the suspend and resume methods in class Thread. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that a thread is not in an appropriate state for the requested operation. See, for example, the suspend and resume methods in class Thread. +/// Since: JDK1.0, CLDC 1.0 public class IllegalThreadStateException extends java.lang.IllegalArgumentException{ - /** - * Constructs an IllegalThreadStateException with no detail message. - */ + /// Constructs an IllegalThreadStateException with no detail message. public IllegalThreadStateException(){ //TODO codavaj!! } - /** - * Constructs an IllegalThreadStateException with the specified detail message. - * s - the detail message. - */ + /// Constructs an IllegalThreadStateException with the specified detail message. + /// s - the detail message. public IllegalThreadStateException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/IncompatibleClassChangeError.java b/Ports/CLDC11/src/java/lang/IncompatibleClassChangeError.java index 2155a28af6..383843c2ad 100644 --- a/Ports/CLDC11/src/java/lang/IncompatibleClassChangeError.java +++ b/Ports/CLDC11/src/java/lang/IncompatibleClassChangeError.java @@ -18,32 +18,29 @@ package java.lang; -/** - * {@code IncompatibleClassChangeError} is the superclass of all classes which - * represent errors that occur when inconsistent class files are loaded into - * the same running image. - * - * @see Error - */ +/// `IncompatibleClassChangeError` is the superclass of all classes which +/// represent errors that occur when inconsistent class files are loaded into +/// the same running image. +/// +/// #### See also +/// +/// - Error public class IncompatibleClassChangeError extends LinkageError { private static final long serialVersionUID = -4914975503642802119L; - /** - * Constructs a new {@code IncompatibleClassChangeError} that includes the - * current stack trace. - */ + /// Constructs a new `IncompatibleClassChangeError` that includes the + /// current stack trace. public IncompatibleClassChangeError() { super(); } - /** - * Constructs a new {@code IncompatibleClassChangeError} with the current - * stack trace and the specified detail message. - * - * @param detailMessage - * the detail message for this error. - */ + /// Constructs a new `IncompatibleClassChangeError` with the current + /// stack trace and the specified detail message. + /// + /// #### Parameters + /// + /// - `detailMessage`: the detail message for this error. public IncompatibleClassChangeError(String detailMessage) { super(detailMessage); } diff --git a/Ports/CLDC11/src/java/lang/IndexOutOfBoundsException.java b/Ports/CLDC11/src/java/lang/IndexOutOfBoundsException.java index a5b59ae067..3bbd97acf6 100644 --- a/Ports/CLDC11/src/java/lang/IndexOutOfBoundsException.java +++ b/Ports/CLDC11/src/java/lang/IndexOutOfBoundsException.java @@ -22,23 +22,17 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that an index of some sort (such as to an array, to a string, or to a vector) is out of range. - * Applications can subclass this class to indicate similar exceptions. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that an index of some sort (such as to an array, to a string, or to a vector) is out of range. +/// Applications can subclass this class to indicate similar exceptions. +/// Since: JDK1.0, CLDC 1.0 public class IndexOutOfBoundsException extends java.lang.RuntimeException{ - /** - * Constructs an IndexOutOfBoundsException with no detail message. - */ + /// Constructs an IndexOutOfBoundsException with no detail message. public IndexOutOfBoundsException(){ //TODO codavaj!! } - /** - * Constructs an IndexOutOfBoundsException with the specified detail message. - * s - the detail message. - */ + /// Constructs an IndexOutOfBoundsException with the specified detail message. + /// s - the detail message. public IndexOutOfBoundsException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/InstantiationException.java b/Ports/CLDC11/src/java/lang/InstantiationException.java index b874239a06..67cc5ac7dc 100644 --- a/Ports/CLDC11/src/java/lang/InstantiationException.java +++ b/Ports/CLDC11/src/java/lang/InstantiationException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the specified class object cannot be instantiated because it is an interface or is an abstract class. - * Since: JDK1.0, CLDC 1.0 See Also:Class.newInstance() - */ +/// Thrown when an application tries to create an instance of a class using the newInstance method in class Class, but the specified class object cannot be instantiated because it is an interface or is an abstract class. +/// Since: JDK1.0, CLDC 1.0 See Also:Class.newInstance() public class InstantiationException extends java.lang.Exception{ - /** - * Constructs an InstantiationException with no detail message. - */ + /// Constructs an InstantiationException with no detail message. public InstantiationException(){ //TODO codavaj!! } - /** - * Constructs an InstantiationException with the specified detail message. - * s - the detail message. - */ + /// Constructs an InstantiationException with the specified detail message. + /// s - the detail message. public InstantiationException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Integer.java b/Ports/CLDC11/src/java/lang/Integer.java index 518703798c..9cda08451c 100644 --- a/Ports/CLDC11/src/java/lang/Integer.java +++ b/Ports/CLDC11/src/java/lang/Integer.java @@ -22,215 +22,180 @@ * have any questions. */ package java.lang; -/** - * The Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int. - * In addition, this class provides several methods for converting an int to a String and a String to an int, as well as other constants and methods useful when dealing with an int. - * Since: JDK1.0, CLDC 1.0 - */ +/// The Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int. +/// In addition, this class provides several methods for converting an int to a String and a String to an int, as well as other constants and methods useful when dealing with an int. +/// Since: JDK1.0, CLDC 1.0 public final class Integer extends Number implements Comparable { public static final Class TYPE = int.class; - /** - * The largest value of type int. The constant value of this field is 2147483647. - * See Also:Constant Field Values - */ + /// The largest value of type int. The constant value of this field is 2147483647. + /// See Also:Constant Field Values public static final int MAX_VALUE=2147483647; - /** - * The smallest value of type int. The constant value of this field is -2147483648. - * See Also:Constant Field Values - */ + /// The smallest value of type int. The constant value of this field is -2147483648. + /// See Also:Constant Field Values public static final int MIN_VALUE=-2147483648; - /** - * Constructs a newly allocated Integer object that represents the primitive int argument. - * value - the value to be represented by the Integer. - */ + /// Constructs a newly allocated Integer object that represents the primitive int argument. + /// value - the value to be represented by the Integer. public Integer(int value){ //TODO codavaj!! } - /** - * Returns the value of this Integer as a byte. - */ + /// Returns the value of this Integer as a byte. public byte byteValue(){ return 0; //TODO codavaj!! } - /** - * Returns the value of this Integer as a double. - */ + /// Returns the value of this Integer as a double. public double doubleValue(){ return 0.0d; //TODO codavaj!! } - /** - * Compares this object to the specified object. The result is true if and only if the argument is not null and is an Integer object that contains the same int value as this object. - */ + /// Compares this object to the specified object. The result is true if and only if the argument is not null and is an Integer object that contains the same int value as this object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the value of this Integer as a float. - */ + /// Returns the value of this Integer as a float. public float floatValue(){ return 0.0f; //TODO codavaj!! } - /** - * Returns a hashcode for this Integer. - */ + /// Returns a hashcode for this Integer. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns the value of this Integer as an int. - */ + /// Returns the value of this Integer as an int. public int intValue(){ return 0; //TODO codavaj!! } - /** - * Returns the value of this Integer as a long. - */ + /// Returns the value of this Integer as a long. public long longValue(){ return 0l; //TODO codavaj!! } - /** - * Parses the string argument as a signed decimal integer. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' (' - * u002d') to indicate a negative value. The resulting integer value is returned, exactly as if the argument and the radix 10 were given as arguments to the - * method. - */ + /// Parses the string argument as a signed decimal integer. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' (' + /// u002d') to indicate a negative value. The resulting integer value is returned, exactly as if the argument and the radix 10 were given as arguments to the + /// method. public static int parseInt(java.lang.String s) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Parses the string argument as a signed integer in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether - * returns a nonnegative value), except that the first character may be an ASCII minus sign '-' (' - * u002d') to indicate a negative value. The resulting integer value is returned. - * An exception of type NumberFormatException is thrown if any of the following situations occurs: The first argument is null or is a string of length zero. The radix is either smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX. Any character of the string is not a digit of the specified radix, except that the first character may be a minus sign '-' ('u002d') provided that the string is longer than length 1. The integer value represented by the string is not a value of type int. - * Examples: - * parseInt("0", 10) returns 0 parseInt("473", 10) returns 473 parseInt("-0", 10) returns 0 parseInt("-FF", 16) returns -255 parseInt("1100110", 2) returns 102 parseInt("2147483647", 10) returns 2147483647 parseInt("-2147483648", 10) returns -2147483648 parseInt("2147483648", 10) throws a NumberFormatException parseInt("99", 8) throws a NumberFormatException parseInt("Kona", 10) throws a NumberFormatException parseInt("Kona", 27) returns 411787 - */ + /// Parses the string argument as a signed integer in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether + /// returns a nonnegative value), except that the first character may be an ASCII minus sign '-' (' + /// u002d') to indicate a negative value. The resulting integer value is returned. + /// An exception of type NumberFormatException is thrown if any of the following situations occurs: The first argument is null or is a string of length zero. The radix is either smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX. Any character of the string is not a digit of the specified radix, except that the first character may be a minus sign '-' ('u002d') provided that the string is longer than length 1. The integer value represented by the string is not a value of type int. + /// Examples: + /// parseInt("0", 10) returns 0 parseInt("473", 10) returns 473 parseInt("-0", 10) returns 0 parseInt("-FF", 16) returns -255 parseInt("1100110", 2) returns 102 parseInt("2147483647", 10) returns 2147483647 parseInt("-2147483648", 10) returns -2147483648 parseInt("2147483648", 10) throws a NumberFormatException parseInt("99", 8) throws a NumberFormatException parseInt("Kona", 10) throws a NumberFormatException parseInt("Kona", 27) returns 411787 public static int parseInt(java.lang.String s, int radix) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Returns the value of this Integer as a short. - */ + /// Returns the value of this Integer as a short. public short shortValue(){ return 0; //TODO codavaj!! } - /** - * Creates a string representation of the integer argument as an unsigned integer in base - * 2. - * The unsigned integer value is the argument plus 232if the argument is negative; otherwise it is equal to the argument. This value is converted to a string of ASCII digits in binary (base2) with no extra leading 0s. If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The characters '0' ('u0030') and '1' ('u0031') are used as binary digits. - */ + /// Creates a string representation of the integer argument as an unsigned integer in base + /// 2. + /// The unsigned integer value is the argument plus 232if the argument is negative; otherwise it is equal to the argument. This value is converted to a string of ASCII digits in binary (base2) with no extra leading 0s. If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The characters '0' ('u0030') and '1' ('u0031') are used as binary digits. public static java.lang.String toBinaryString(int i){ return null; //TODO codavaj!! } - /** - * Creates a string representation of the integer argument as an unsigned integer in base - * 16. - * The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in hexadecimal (base16) with no extra leading 0s. If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The following characters are used as hexadecimal digits: - * 0123456789abcdef These are the characters ' - * u0030' through ' - * u0039' and 'u\0039' through ' - * u0066'. - */ + /// Creates a string representation of the integer argument as an unsigned integer in base + /// 16. + /// The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in hexadecimal (base16) with no extra leading 0s. If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The following characters are used as hexadecimal digits: + /// 0123456789abcdef These are the characters ' + /// u0030' through ' + /// u0039' and 'u\0039' through ' + /// u0066'. public static java.lang.String toHexString(int i){ return null; //TODO codavaj!! } - /** - * Creates a string representation of the integer argument as an unsigned integer in base 8. - * The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in octal (base8) with no extra leading 0s. - * If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The octal digits are: - * 01234567 These are the characters ' - * u0030' through ' - * u0037'. - */ + /// Creates a string representation of the integer argument as an unsigned integer in base 8. + /// The unsigned integer value is the argument plus 232 if the argument is negative; otherwise, it is equal to the argument. This value is converted to a string of ASCII digits in octal (base8) with no extra leading 0s. + /// If the unsigned magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the unsigned magnitude will not be the zero character. The octal digits are: + /// 01234567 These are the characters ' + /// u0030' through ' + /// u0037'. public static java.lang.String toOctalString(int i){ return null; //TODO codavaj!! } - /** - * Returns a String object representing this Integer's value. The value is converted to signed decimal representation and returned as a string, exactly as if the integer value were given as an argument to the - * method. - */ + /// Returns a String object representing this Integer's value. The value is converted to signed decimal representation and returned as a string, exactly as if the integer value were given as an argument to the + /// method. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns a new String object representing the specified integer. The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and radix 10 were given as arguments to the - * method. - */ + /// Returns a new String object representing the specified integer. The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and radix 10 were given as arguments to the + /// method. public static java.lang.String toString(int i){ return null; //TODO codavaj!! } - /** - * Creates a string representation of the first argument in the radix specified by the second argument. - * If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead. - * If the first argument is negative, the first element of the result is the ASCII minus character '-' ('u002d'). If the first argument is not negative, no sign character appears in the result. - * The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character. The following ASCII characters are used as digits: - * 0123456789abcdefghijklmnopqrstuvwxyz These are ' - * u0030' through ' - * u0039' and ' - * u0061' through ' - * u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. - */ + /// Creates a string representation of the first argument in the radix specified by the second argument. + /// If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead. + /// If the first argument is negative, the first element of the result is the ASCII minus character '-' ('u002d'). If the first argument is not negative, no sign character appears in the result. + /// The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character. The following ASCII characters are used as digits: + /// 0123456789abcdefghijklmnopqrstuvwxyz These are ' + /// u0030' through ' + /// u0039' and ' + /// u0061' through ' + /// u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. public static java.lang.String toString(int i, int radix){ return null; //TODO codavaj!! } - /** - * Returns a new Integer object initialized to the value of the specified String. The argument is interpreted as representing a signed decimal integer, exactly as if the argument were given to the - * method. The result is an Integer object that represents the integer value specified by the string. - * In other words, this method returns an Integer object equal to the value of: - * new Integer(Integer.parseInt(s)) - */ + /// Returns a new Integer object initialized to the value of the specified String. The argument is interpreted as representing a signed decimal integer, exactly as if the argument were given to the + /// method. The result is an Integer object that represents the integer value specified by the string. + /// In other words, this method returns an Integer object equal to the value of: + /// new Integer(Integer.parseInt(s)) public static java.lang.Integer valueOf(java.lang.String s) throws java.lang.NumberFormatException{ return null; //TODO codavaj!! } - /** - * Returns a new Integer object initialized to the value of the specified String. The first argument is interpreted as representing a signed integer in the radix specified by the second argument, exactly as if the arguments were given to the - * method. The result is an Integer object that represents the integer value specified by the string. - * In other words, this method returns an Integer object equal to the value of: - * new Integer(Integer.parseInt(s, radix)) - */ + /// Returns a new Integer object initialized to the value of the specified String. The first argument is interpreted as representing a signed integer in the radix specified by the second argument, exactly as if the arguments were given to the + /// method. The result is an Integer object that represents the integer value specified by the string. + /// In other words, this method returns an Integer object equal to the value of: + /// new Integer(Integer.parseInt(s, radix)) public static java.lang.Integer valueOf(java.lang.String s, int radix) throws java.lang.NumberFormatException{ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Integer valueOf(int i) { return null; } - /** - * Returns the value of the {@code signum} function for the specified - * integer. - * - * @param i - * the integer value to check. - * @return -1 if {@code i} is negative, 1 if {@code i} is positive, 0 if - * {@code i} is zero. - * @since 1.5 - */ + /// Returns the value of the `signum` function for the specified + /// integer. + /// + /// #### Parameters + /// + /// - `i`: the integer value to check. + /// + /// #### Returns + /// + /// @return -1 if `i` is negative, 1 if `i` is positive, 0 if + /// `i` is zero. + /// + /// #### Since + /// + /// 1.5 public static int signum(int i) { return (i >> 31) | (-i >>> 31); // Hacker's delight 2-7 } diff --git a/Ports/CLDC11/src/java/lang/InterruptedException.java b/Ports/CLDC11/src/java/lang/InterruptedException.java index 7532f4cc22..698d558a27 100644 --- a/Ports/CLDC11/src/java/lang/InterruptedException.java +++ b/Ports/CLDC11/src/java/lang/InterruptedException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown when a thread is waiting, sleeping, or otherwise paused for a long time and another thread interrupts it. - * Since: JDK1.0, CLDC 1.0 See Also:Object.wait(), Object.wait(long), Object.wait(long, int), Thread.sleep(long) - */ +/// Thrown when a thread is waiting, sleeping, or otherwise paused for a long time and another thread interrupts it. +/// Since: JDK1.0, CLDC 1.0 See Also:Object.wait(), Object.wait(long), Object.wait(long, int), Thread.sleep(long) public class InterruptedException extends java.lang.Exception{ - /** - * Constructs an InterruptedException with no detail message. - */ + /// Constructs an InterruptedException with no detail message. public InterruptedException(){ //TODO codavaj!! } - /** - * Constructs an InterruptedException with the specified detail message. - * s - the detail message. - */ + /// Constructs an InterruptedException with the specified detail message. + /// s - the detail message. public InterruptedException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Iterable.java b/Ports/CLDC11/src/java/lang/Iterable.java index 31883fb0b8..66f86db1f6 100644 --- a/Ports/CLDC11/src/java/lang/Iterable.java +++ b/Ports/CLDC11/src/java/lang/Iterable.java @@ -18,18 +18,18 @@ import java.util.Iterator; -/** - * Objects of classes that implement this interface can be used within a - * {@code foreach} statement. - * - * @since 1.5 - */ +/// Objects of classes that implement this interface can be used within a +/// `foreach` statement. +/// +/// #### Since +/// +/// 1.5 public interface Iterable { - /** - * Returns an {@link Iterator} for the elements in this object. - * - * @return An {@code Iterator} instance. - */ + /// Returns an `Iterator` for the elements in this object. + /// + /// #### Returns + /// + /// An `Iterator` instance. Iterator iterator(); } diff --git a/Ports/CLDC11/src/java/lang/LinkageError.java b/Ports/CLDC11/src/java/lang/LinkageError.java index 061f3dc640..7a8a458828 100644 --- a/Ports/CLDC11/src/java/lang/LinkageError.java +++ b/Ports/CLDC11/src/java/lang/LinkageError.java @@ -18,31 +18,28 @@ package java.lang; -/** - * {@code LinkageError} is the superclass of all error classes that occur when - * loading and linking class files. - * - * @see Error - */ +/// `LinkageError` is the superclass of all error classes that occur when +/// loading and linking class files. +/// +/// #### See also +/// +/// - Error public class LinkageError extends Error { private static final long serialVersionUID = 3579600108157160122L; - /** - * Constructs a new {@code LinkageError} that includes the current stack - * trace. - */ + /// Constructs a new `LinkageError` that includes the current stack + /// trace. public LinkageError() { super(); } - /** - * Constructs a new {@code LinkageError} with the current stack trace and - * the specified detail message. - * - * @param detailMessage - * the detail message for this error. - */ + /// Constructs a new `LinkageError` with the current stack trace and + /// the specified detail message. + /// + /// #### Parameters + /// + /// - `detailMessage`: the detail message for this error. public LinkageError(String detailMessage) { super(detailMessage); } diff --git a/Ports/CLDC11/src/java/lang/Long.java b/Ports/CLDC11/src/java/lang/Long.java index 97181599cd..442dd006c9 100644 --- a/Ports/CLDC11/src/java/lang/Long.java +++ b/Ports/CLDC11/src/java/lang/Long.java @@ -22,140 +22,112 @@ * have any questions. */ package java.lang; -/** - * The Long class wraps a value of the primitive type long in an object. An object of type Long contains a single field whose type is long. - * In addition, this class provides several methods for converting a long to a String and a String to a long, as well as other constants and methods useful when dealing with a long. - * Since: JDK1.0, CLDC 1.0 - */ +/// The Long class wraps a value of the primitive type long in an object. An object of type Long contains a single field whose type is long. +/// In addition, this class provides several methods for converting a long to a String and a String to a long, as well as other constants and methods useful when dealing with a long. +/// Since: JDK1.0, CLDC 1.0 public final class Long extends Number implements Comparable{ public static Class TYPE = long.class; - /** - * The largest value of type long. - * See Also:Constant Field Values - */ + /// The largest value of type long. + /// See Also:Constant Field Values public static final long MAX_VALUE=9223372036854775807l; - /** - * The smallest value of type long. - * See Also:Constant Field Values - */ + /// The smallest value of type long. + /// See Also:Constant Field Values public static final long MIN_VALUE=-9223372036854775808l; - /** - * Constructs a newly allocated Long object that represents the primitive long argument. - * value - the value to be represented by the Long object. - */ + /// Constructs a newly allocated Long object that represents the primitive long argument. + /// value - the value to be represented by the Long object. public Long(long value){ //TODO codavaj!! } - /** - * Returns the value of this Long as a double. - */ + /// Returns the value of this Long as a double. public double doubleValue(){ return 0.0d; //TODO codavaj!! } - /** - * Compares this object against the specified object. The result is true if and only if the argument is not null and is a Long object that contains the same long value as this object. - */ + /// Compares this object against the specified object. The result is true if and only if the argument is not null and is a Long object that contains the same long value as this object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the value of this Long as a float. - */ + /// Returns the value of this Long as a float. public float floatValue(){ return 0.0f; //TODO codavaj!! } - /** - * Computes a hashcode for this Long. The result is the exclusive OR of the two halves of the primitive long value represented by this Long object. That is, the hashcode is the value of the expression: (int)(this.longValue()^(this.longValue()>>>32)) - */ + /// Computes a hashcode for this Long. The result is the exclusive OR of the two halves of the primitive long value represented by this Long object. That is, the hashcode is the value of the expression: (int)(this.longValue()^(this.longValue()>>>32)) public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns the value of this Long as a long value. - */ + /// Returns the value of this Long as a long value. public long longValue(){ return 0l; //TODO codavaj!! } - /** - * Returns the value of this Long as an int value. - */ + /// Returns the value of this Long as an int value. public int intValue() { return 0; } - /** - * Returns the value of this Long as a byte value. - */ + /// Returns the value of this Long as a byte value. public byte byteValue() { return (byte)0; } - /** - * Parses the string argument as a signed decimal long. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' ( - * u002d') to indicate a negative value. The resulting long value is returned, exactly as if the argument and the radix 10 were given as arguments to the - * method that takes two arguments. - * Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java programming language source code. - */ + /// Parses the string argument as a signed decimal long. The characters in the string must all be decimal digits, except that the first character may be an ASCII minus sign '-' ( + /// u002d') to indicate a negative value. The resulting long value is returned, exactly as if the argument and the radix 10 were given as arguments to the + /// method that takes two arguments. + /// Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java programming language source code. public static long parseLong(java.lang.String s) throws java.lang.NumberFormatException{ return 0l; //TODO codavaj!! } - /** - * Parses the string argument as a signed long in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether Character.digit returns a nonnegative value), except that the first character may be an ASCII minus sign '-' (' - * u002d' to indicate a negative value. The resulting long value is returned. - * Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java programming language source code - except that either L or l may appear as a digit for a radix greater than 22. - * An exception of type NumberFormatException is thrown if any of the following situations occurs: The first argument is null or is a string of length zero. The radix is either smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX. The first character of the string is not a digit of the specified radix and is not a minus sign '-' ('u002d'). The first character of the string is a minus sign and the string is of length 1. Any character of the string after the first is not a digit of the specified radix. The integer value represented by the string cannot be represented as a value of type long. - * Examples: - * parseLong("0", 10) returns 0L parseLong("473", 10) returns 473L parseLong("-0", 10) returns 0L parseLong("-FF", 16) returns -255L parseLong("1100110", 2) returns 102L parseLong("99", 8) throws a NumberFormatException parseLong("Hazelnut", 10) throws a NumberFormatException parseLong("Hazelnut", 36) returns 1356099454469L - */ + /// Parses the string argument as a signed long in the radix specified by the second argument. The characters in the string must all be digits of the specified radix (as determined by whether Character.digit returns a nonnegative value), except that the first character may be an ASCII minus sign '-' (' + /// u002d' to indicate a negative value. The resulting long value is returned. + /// Note that neither L nor l is permitted to appear at the end of the string as a type indicator, as would be permitted in Java programming language source code - except that either L or l may appear as a digit for a radix greater than 22. + /// An exception of type NumberFormatException is thrown if any of the following situations occurs: The first argument is null or is a string of length zero. The radix is either smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX. The first character of the string is not a digit of the specified radix and is not a minus sign '-' ('u002d'). The first character of the string is a minus sign and the string is of length 1. Any character of the string after the first is not a digit of the specified radix. The integer value represented by the string cannot be represented as a value of type long. + /// Examples: + /// parseLong("0", 10) returns 0L parseLong("473", 10) returns 473L parseLong("-0", 10) returns 0L parseLong("-FF", 16) returns -255L parseLong("1100110", 2) returns 102L parseLong("99", 8) throws a NumberFormatException parseLong("Hazelnut", 10) throws a NumberFormatException parseLong("Hazelnut", 36) returns 1356099454469L public static long parseLong(java.lang.String s, int radix) throws java.lang.NumberFormatException{ return 0l; //TODO codavaj!! } - /** - * Returns a String object representing this Long's value. The long integer value represented by this Long object is converted to signed decimal representation and returned as a string, exactly as if the long value were given as an argument to the - * method that takes one argument. - */ + /// Returns a String object representing this Long's value. The long integer value represented by this Long object is converted to signed decimal representation and returned as a string, exactly as if the long value were given as an argument to the + /// method that takes one argument. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns a new String object representing the specified integer. The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and the radix 10 were given as arguments to the - * method that takes two arguments. - */ + /// Returns a new String object representing the specified integer. The argument is converted to signed decimal representation and returned as a string, exactly as if the argument and the radix 10 were given as arguments to the + /// method that takes two arguments. public static java.lang.String toString(long i){ return null; //TODO codavaj!! } - /** - * Creates a string representation of the first argument in the radix specified by the second argument. - * If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead. - * If the first argument is negative, the first element of the result is the ASCII minus sign '-' ('u002d'. If the first argument is not negative, no sign character appears in the result. - * The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character. The following ASCII characters are used as digits: - * 0123456789abcdefghijklmnopqrstuvwxyz These are ' - * u0030' through ' - * u0039' and ' - * u0061' through ' - * u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. - */ + /// Creates a string representation of the first argument in the radix specified by the second argument. + /// If the radix is smaller than Character.MIN_RADIX or larger than Character.MAX_RADIX, then the radix 10 is used instead. + /// If the first argument is negative, the first element of the result is the ASCII minus sign '-' ('u002d'. If the first argument is not negative, no sign character appears in the result. + /// The remaining characters of the result represent the magnitude of the first argument. If the magnitude is zero, it is represented by a single zero character '0' ('u0030'); otherwise, the first character of the representation of the magnitude will not be the zero character. The following ASCII characters are used as digits: + /// 0123456789abcdefghijklmnopqrstuvwxyz These are ' + /// u0030' through ' + /// u0039' and ' + /// u0061' through ' + /// u007a'. If the radix is N, then the first N of these characters are used as radix-N digits in the order shown. Thus, the digits for hexadecimal (radix 16) are 0123456789abcdef. public static java.lang.String toString(long i, int radix){ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Long valueOf(long i) { return null; } diff --git a/Ports/CLDC11/src/java/lang/Math.java b/Ports/CLDC11/src/java/lang/Math.java index fddac9c222..8129b172ad 100644 --- a/Ports/CLDC11/src/java/lang/Math.java +++ b/Ports/CLDC11/src/java/lang/Math.java @@ -22,187 +22,148 @@ * have any questions. */ package java.lang; -/** - * The class Math contains methods for performing basic numeric operations. - * Since: JDK1.0, CLDC 1.0 - */ +/// The class Math contains methods for performing basic numeric operations. +/// Since: JDK1.0, CLDC 1.0 public final class Math{ - /** - * The double value that is closer than any other to e, the base of the natural logarithms. - * Since: CLDC 1.1 See Also:Constant Field Values - */ + /// The double value that is closer than any other to e, the base of the natural logarithms. + /// Since: CLDC 1.1 See Also:Constant Field Values public static final double E=2.718281828459045d; - /** - * The double value that is closer than any other to - * , the ratio of the circumference of a circle to its diameter. - * Since: CLDC 1.1 See Also:Constant Field Values - */ + /// The double value that is closer than any other to + /// , the ratio of the circumference of a circle to its diameter. + /// Since: CLDC 1.1 See Also:Constant Field Values public static final double PI=3.141592653589793d; - /** - * Returns the absolute value of a double value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. Special cases: If the argument is positive zero or negative zero, the result is positive zero. If the argument is infinite, the result is positive infinity. If the argument is NaN, the result is NaN. In other words, the result is equal to the value of the expression: - * Double.longBitsToDouble((Double.doubleToLongBits(a)<<1)>>>1) - */ + /// Returns the absolute value of a double value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. Special cases: If the argument is positive zero or negative zero, the result is positive zero. If the argument is infinite, the result is positive infinity. If the argument is NaN, the result is NaN. In other words, the result is equal to the value of the expression: + /// Double.longBitsToDouble((Double.doubleToLongBits(a)>>1) public static double abs(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the absolute value of a float value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. Special cases: If the argument is positive zero or negative zero, the result is positive zero. If the argument is infinite, the result is positive infinity. If the argument is NaN, the result is NaN. In other words, the result is equal to the value of the expression: - * Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a)) - */ + /// Returns the absolute value of a float value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. Special cases: If the argument is positive zero or negative zero, the result is positive zero. If the argument is infinite, the result is positive infinity. If the argument is NaN, the result is NaN. In other words, the result is equal to the value of the expression: + /// Float.intBitsToFloat(0x7fffffff & Float.floatToIntBits(a)) public static float abs(float a){ return 0.0f; //TODO codavaj!! } - /** - * Returns the absolute value of an int value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. - * Note that if the argument is equal to the value of Integer.MIN_VALUE, the most negative representable int value, the result is that same value, which is negative. - */ + /// Returns the absolute value of an int value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. + /// Note that if the argument is equal to the value of Integer.MIN_VALUE, the most negative representable int value, the result is that same value, which is negative. public static int abs(int a){ return 0; //TODO codavaj!! } - /** - * Returns the absolute value of a long value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. - * Note that if the argument is equal to the value of Long.MIN_VALUE, the most negative representable long value, the result is that same value, which is negative. - */ + /// Returns the absolute value of a long value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. + /// Note that if the argument is equal to the value of Long.MIN_VALUE, the most negative representable long value, the result is that same value, which is negative. public static long abs(long a){ return 0l; //TODO codavaj!! } - /** - * Returns the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer. Special cases: If the argument value is already equal to a mathematical integer, then the result is the same as the argument. If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument. If the argument value is less than zero but greater than -1.0, then the result is negative zero. Note that the value of Math.ceil(x) is exactly the value of -Math.floor(-x). - */ + /// Returns the smallest (closest to negative infinity) double value that is not less than the argument and is equal to a mathematical integer. Special cases: If the argument value is already equal to a mathematical integer, then the result is the same as the argument. If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument. If the argument value is less than zero but greater than -1.0, then the result is negative zero. Note that the value of Math.ceil(x) is exactly the value of -Math.floor(-x). public static double ceil(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the trigonometric cosine of an angle. Special case: If the argument is NaN or an infinity, then the result is NaN. - */ + /// Returns the trigonometric cosine of an angle. Special case: If the argument is NaN or an infinity, then the result is NaN. public static double cos(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer. Special cases: If the argument value is already equal to a mathematical integer, then the result is the same as the argument. If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument. - */ + /// Returns the largest (closest to positive infinity) double value that is not greater than the argument and is equal to a mathematical integer. Special cases: If the argument value is already equal to a mathematical integer, then the result is the same as the argument. If the argument is NaN or an infinity or positive zero or negative zero, then the result is the same as the argument. public static double floor(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the greater of two double values. That is, the result is the argument closer to positive infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other negative zero, the result is positive zero. - */ + /// Returns the greater of two double values. That is, the result is the argument closer to positive infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other negative zero, the result is positive zero. public static double max(double a, double b){ return 0.0d; //TODO codavaj!! } - /** - * Returns the greater of two float values. That is, the result is the argument closer to positive infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other negative zero, the result is positive zero. - */ + /// Returns the greater of two float values. That is, the result is the argument closer to positive infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other negative zero, the result is positive zero. public static float max(float a, float b){ return 0.0f; //TODO codavaj!! } - /** - * Returns the greater of two int values. That is, the result is the argument closer to the value of Integer.MAX_VALUE. If the arguments have the same value, the result is that same value. - */ + /// Returns the greater of two int values. That is, the result is the argument closer to the value of Integer.MAX_VALUE. If the arguments have the same value, the result is that same value. public static int max(int a, int b){ return 0; //TODO codavaj!! } - /** - * Returns the greater of two long values. That is, the result is the argument closer to the value of Long.MAX_VALUE. If the arguments have the same value, the result is that same value. - */ + /// Returns the greater of two long values. That is, the result is the argument closer to the value of Long.MAX_VALUE. If the arguments have the same value, the result is that same value. public static long max(long a, long b){ return 0l; //TODO codavaj!! } - /** - * Returns the smaller of two double values. That is, the result is the value closer to negative infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other is negative zero, the result is negative zero. - */ + /// Returns the smaller of two double values. That is, the result is the value closer to negative infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other is negative zero, the result is negative zero. public static double min(double a, double b){ return 0.0d; //TODO codavaj!! } - /** - * Returns the smaller of two float values. That is, the result is the value closer to negative infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other is negative zero, the result is negative zero. - */ + /// Returns the smaller of two float values. That is, the result is the value closer to negative infinity. If the arguments have the same value, the result is that same value. If either value is NaN, then the result is NaN. Unlike the the numerical comparison operators, this method considers negative zero to be strictly smaller than positive zero. If one argument is positive zero and the other is negative zero, the result is negative zero. public static float min(float a, float b){ return 0.0f; //TODO codavaj!! } - /** - * Returns the smaller of two int values. That is, the result the argument closer to the value of Integer.MIN_VALUE. If the arguments have the same value, the result is that same value. - */ + /// Returns the smaller of two int values. That is, the result the argument closer to the value of Integer.MIN_VALUE. If the arguments have the same value, the result is that same value. public static int min(int a, int b){ return 0; //TODO codavaj!! } - /** - * Returns the smaller of two long values. That is, the result is the argument closer to the value of Long.MIN_VALUE. If the arguments have the same value, the result is that same value. - */ + /// Returns the smaller of two long values. That is, the result is the argument closer to the value of Long.MIN_VALUE. If the arguments have the same value, the result is that same value. public static long min(long a, long b){ return 0l; //TODO codavaj!! } - /** - * Returns the trigonometric sine of an angle. Special cases: If the argument is NaN or an infinity, then the result is NaN. If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero. - */ + /// Returns the trigonometric sine of an angle. Special cases: If the argument is NaN or an infinity, then the result is NaN. If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero. public static double sin(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the correctly rounded positive square root of a double value. Special cases: If the argument is NaN or less than zero, then the result is NaN. If the argument is positive infinity, then the result is positive infinity. If the argument is positive zero or negative zero, then the result is the same as the argument. - */ + /// Returns the correctly rounded positive square root of a double value. Special cases: If the argument is NaN or less than zero, then the result is NaN. If the argument is positive infinity, then the result is positive infinity. If the argument is positive zero or negative zero, then the result is the same as the argument. public static double sqrt(double a){ return 0.0d; //TODO codavaj!! } - /** - * Returns the trigonometric tangent of an angle. Special cases: If the argument is NaN or an infinity, then the result is NaN. If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero - */ + /// Returns the trigonometric tangent of an angle. Special cases: If the argument is NaN or an infinity, then the result is NaN. If the argument is positive zero, then the result is positive zero; if the argument is negative zero, then the result is negative zero public static double tan(double a){ return 0.0d; //TODO codavaj!! } - /** - * Converts an angle measured in radians to the equivalent angle measured in degrees. - */ + /// Converts an angle measured in radians to the equivalent angle measured in degrees. public static double toDegrees(double angrad){ return 0.0d; //TODO codavaj!! } - /** - * Converts an angle measured in degrees to the equivalent angle measured in radians. - */ + /// Converts an angle measured in degrees to the equivalent angle measured in radians. public static double toRadians(double angdeg){ return 0.0d; //TODO codavaj!! } - /** - * Returns the result of rounding the argument to an integer. The result is - * equivalent to {@code (long) Math.floor(d+0.5)}. - *

- * Special cases: - *

    - *
  • {@code round(+0.0) = (long) +0.0}
    • - *
  • {@code round(-0.0) = (long) +0.0}
    • - *
  • {@code round((anything > Long.MAX_VALUE) = Long.MAX_VALUE}
    • - *
  • {@code round((anything < Long.MIN_VALUE) = Long.MIN_VALUE}
    • - *
  • {@code round(+infinity) = Long.MAX_VALUE}
    • - *
  • {@code round(-infinity) = Long.MIN_VALUE}
    • - *
  • {@code round(NaN) = (long) +0.0}
    • - *
- * - * @param d - * the value to be rounded. - * @return the closest integer to the argument. - */ + /// Returns the result of rounding the argument to an integer. The result is + /// equivalent to `(long) Math.floor(d+0.5)`. + /// + /// Special cases: + /// + /// - `round(+0.0) = (long) +0.0` + /// + /// - `round(-0.0) = (long) +0.0` + /// + /// - `round((anything > Long.MAX_VALUE) = Long.MAX_VALUE` + /// + /// - `round((anything < Long.MIN_VALUE) = Long.MIN_VALUE` + /// + /// - `round(+infinity) = Long.MAX_VALUE` + /// + /// - `round(-infinity) = Long.MIN_VALUE` + /// + /// - `round(NaN) = (long) +0.0` + /// + /// #### Parameters + /// + /// - `d`: the value to be rounded. + /// + /// #### Returns + /// + /// the closest integer to the argument. public static long round(double d) { // check for NaN if (d != d) { @@ -211,25 +172,32 @@ public static long round(double d) { return (long) floor(d + 0.5d); } - /** - * Returns the result of rounding the argument to an integer. The result is - * equivalent to {@code (int) Math.floor(f+0.5)}. - *

- * Special cases: - *

    - *
  • {@code round(+0.0) = (int) +0.0}
    • - *
  • {@code round(-0.0) = (int) +0.0}
    • - *
  • {@code round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE}
    • - *
  • {@code round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE}
    • - *
  • {@code round(+infinity) = Integer.MAX_VALUE}
    • - *
  • {@code round(-infinity) = Integer.MIN_VALUE}
    • - *
  • {@code round(NaN) = (int) +0.0}
    • - *
- * - * @param f - * the value to be rounded. - * @return the closest integer to the argument. - */ + /// Returns the result of rounding the argument to an integer. The result is + /// equivalent to `(int) Math.floor(f+0.5)`. + /// + /// Special cases: + /// + /// - `round(+0.0) = (int) +0.0` + /// + /// - `round(-0.0) = (int) +0.0` + /// + /// - `round((anything > Integer.MAX_VALUE) = Integer.MAX_VALUE` + /// + /// - `round((anything < Integer.MIN_VALUE) = Integer.MIN_VALUE` + /// + /// - `round(+infinity) = Integer.MAX_VALUE` + /// + /// - `round(-infinity) = Integer.MIN_VALUE` + /// + /// - `round(NaN) = (int) +0.0` + /// + /// #### Parameters + /// + /// - `f`: the value to be rounded. + /// + /// #### Returns + /// + /// the closest integer to the argument. public static int round(float f) { // check for NaN if (f != f) { diff --git a/Ports/CLDC11/src/java/lang/NegativeArraySizeException.java b/Ports/CLDC11/src/java/lang/NegativeArraySizeException.java index 7c53c33e00..faefbed32d 100644 --- a/Ports/CLDC11/src/java/lang/NegativeArraySizeException.java +++ b/Ports/CLDC11/src/java/lang/NegativeArraySizeException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown if an application tries to create an array with negative size. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown if an application tries to create an array with negative size. +/// Since: JDK1.0, CLDC 1.0 public class NegativeArraySizeException extends java.lang.RuntimeException{ - /** - * Constructs a NegativeArraySizeException with no detail message. - */ + /// Constructs a NegativeArraySizeException with no detail message. public NegativeArraySizeException(){ //TODO codavaj!! } - /** - * Constructs a NegativeArraySizeException with the specified detail message. - * s - the detail message. - */ + /// Constructs a NegativeArraySizeException with the specified detail message. + /// s - the detail message. public NegativeArraySizeException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/NoClassDefFoundError.java b/Ports/CLDC11/src/java/lang/NoClassDefFoundError.java index 166d4a304b..10df79daac 100644 --- a/Ports/CLDC11/src/java/lang/NoClassDefFoundError.java +++ b/Ports/CLDC11/src/java/lang/NoClassDefFoundError.java @@ -22,23 +22,17 @@ * have any questions. */ package java.lang; -/** - * Thrown if the Java Virtual Machine tries to load in the definition of a class (as part of a normal method call or as part of creating a new instance using the new expression) and no definition of the class could be found. - * The searched-for class definition existed when the currently executing class was compiled, but the definition can no longer be found. - * Since: JDK1.0, CLDC 1.1 - */ +/// Thrown if the Java Virtual Machine tries to load in the definition of a class (as part of a normal method call or as part of creating a new instance using the new expression) and no definition of the class could be found. +/// The searched-for class definition existed when the currently executing class was compiled, but the definition can no longer be found. +/// Since: JDK1.0, CLDC 1.1 public class NoClassDefFoundError extends java.lang.Error{ - /** - * Constructs a NoClassDefFoundError with no detail message. - */ + /// Constructs a NoClassDefFoundError with no detail message. public NoClassDefFoundError(){ //TODO codavaj!! } - /** - * Constructs a NoClassDefFoundError with the specified detail message. - * s - the detail message. - */ + /// Constructs a NoClassDefFoundError with the specified detail message. + /// s - the detail message. public NoClassDefFoundError(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/NoSuchFieldError.java b/Ports/CLDC11/src/java/lang/NoSuchFieldError.java index 9b479f644b..7ac9d81f6b 100644 --- a/Ports/CLDC11/src/java/lang/NoSuchFieldError.java +++ b/Ports/CLDC11/src/java/lang/NoSuchFieldError.java @@ -17,31 +17,26 @@ package java.lang; -/** - * Thrown when the virtual machine notices that a program tries to reference, - * on a class or object, a field that does not exist. - *

- * Note that this can only occur when inconsistent class files are being loaded. - */ +/// Thrown when the virtual machine notices that a program tries to reference, +/// on a class or object, a field that does not exist. +/// +/// Note that this can only occur when inconsistent class files are being loaded. public class NoSuchFieldError extends IncompatibleClassChangeError { private static final long serialVersionUID = -3456430195886129035L; - /** - * Constructs a new {@code NoSuchFieldError} that includes the current stack - * trace. - */ + /// Constructs a new `NoSuchFieldError` that includes the current stack + /// trace. public NoSuchFieldError() { super(); } - /** - * Constructs a new {@code NoSuchFieldError} with the current stack trace - * and the specified detail message. - * - * @param detailMessage - * the detail message for this error. - */ + /// Constructs a new `NoSuchFieldError` with the current stack trace + /// and the specified detail message. + /// + /// #### Parameters + /// + /// - `detailMessage`: the detail message for this error. public NoSuchFieldError(String detailMessage) { super(detailMessage); } diff --git a/Ports/CLDC11/src/java/lang/NullPointerException.java b/Ports/CLDC11/src/java/lang/NullPointerException.java index 461967121b..213b83d1b1 100644 --- a/Ports/CLDC11/src/java/lang/NullPointerException.java +++ b/Ports/CLDC11/src/java/lang/NullPointerException.java @@ -22,23 +22,17 @@ * have any questions. */ package java.lang; -/** - * Thrown when an application attempts to use null in a case where an object is required. These include: Calling the instance method of a null object. Accessing or modifying the field of a null object. Taking the length of null as if it were an array. Accessing or modifying the slots of null as if it were an array. Throwing null as if it were a Throwable value. - * Applications should throw instances of this class to indicate other illegal uses of the null object. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown when an application attempts to use null in a case where an object is required. These include: Calling the instance method of a null object. Accessing or modifying the field of a null object. Taking the length of null as if it were an array. Accessing or modifying the slots of null as if it were an array. Throwing null as if it were a Throwable value. +/// Applications should throw instances of this class to indicate other illegal uses of the null object. +/// Since: JDK1.0, CLDC 1.0 public class NullPointerException extends java.lang.RuntimeException{ - /** - * Constructs a NullPointerException with no detail message. - */ + /// Constructs a NullPointerException with no detail message. public NullPointerException(){ //TODO codavaj!! } - /** - * Constructs a NullPointerException with the specified detail message. - * s - the detail message. - */ + /// Constructs a NullPointerException with the specified detail message. + /// s - the detail message. public NullPointerException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Number.java b/Ports/CLDC11/src/java/lang/Number.java index 9104fa5fe8..2c96b3a92a 100644 --- a/Ports/CLDC11/src/java/lang/Number.java +++ b/Ports/CLDC11/src/java/lang/Number.java @@ -22,10 +22,7 @@ */ package java.lang; -/** - * - * @author shannah - */ +/// @author shannah public abstract class Number { public abstract int intValue(); diff --git a/Ports/CLDC11/src/java/lang/NumberFormatException.java b/Ports/CLDC11/src/java/lang/NumberFormatException.java index 3a6cc212a9..91321c6565 100644 --- a/Ports/CLDC11/src/java/lang/NumberFormatException.java +++ b/Ports/CLDC11/src/java/lang/NumberFormatException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that the application has attempted to convert a string to one of the numeric types, but that the string does not have the appropriate format. - * Since: JDK1.0, CLDC 1.0 See Also:Integer.toString() - */ +/// Thrown to indicate that the application has attempted to convert a string to one of the numeric types, but that the string does not have the appropriate format. +/// Since: JDK1.0, CLDC 1.0 See Also:Integer.toString() public class NumberFormatException extends java.lang.IllegalArgumentException{ - /** - * Constructs a NumberFormatException with no detail message. - */ + /// Constructs a NumberFormatException with no detail message. public NumberFormatException(){ //TODO codavaj!! } - /** - * Constructs a NumberFormatException with the specified detail message. - * s - the detail message. - */ + /// Constructs a NumberFormatException with the specified detail message. + /// s - the detail message. public NumberFormatException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Object.java b/Ports/CLDC11/src/java/lang/Object.java index ab1ab26ca0..32317dd8ac 100644 --- a/Ports/CLDC11/src/java/lang/Object.java +++ b/Ports/CLDC11/src/java/lang/Object.java @@ -22,105 +22,85 @@ * have any questions. */ package java.lang; -/** - * Class Object is the root of the class hierarchy. Every class has Object as a superclass. All objects, including arrays, implement the methods of this class. - * Since: JDK1.0, CLDC 1.0 See Also:Class - */ +/// Class Object is the root of the class hierarchy. Every class has Object as a superclass. All objects, including arrays, implement the methods of this class. +/// Since: JDK1.0, CLDC 1.0 See Also:Class public class Object{ public Object(){ //TODO codavaj!! } - /** - * Indicates whether some other object is "equal to" this one. - * The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. - * The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true). - */ + /// Indicates whether some other object is "equal to" this one. + /// The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. + /// The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true). public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the runtime class of an object. That Class object is the object that is locked by static synchronized methods of the represented class. - */ + /// Returns the runtime class of an object. That Class object is the object that is locked by static synchronized methods of the represented class. public final java.lang.Class getClass(){ return null; //TODO codavaj!! } - /** - * Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. - * The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. - * As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.) - */ + /// Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. + /// The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. + /// As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.) public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Wakes up a single thread that is waiting on this object's monitor. If any threads are waiting on this object, one of them is chosen to be awakened. The choice is arbitrary and occurs at the discretion of the implementation. A thread waits on an object's monitor by calling one of the wait methods. - * The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object. - * This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways: By executing a synchronized instance method of that object. By executing the body of a synchronized statement that synchronizes on the object. For objects of type Class, by executing a synchronized static method of that class. - * Only one thread at a time can own an object's monitor. - */ + /// Wakes up a single thread that is waiting on this object's monitor. If any threads are waiting on this object, one of them is chosen to be awakened. The choice is arbitrary and occurs at the discretion of the implementation. A thread waits on an object's monitor by calling one of the wait methods. + /// The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object. + /// This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways: By executing a synchronized instance method of that object. By executing the body of a synchronized statement that synchronizes on the object. For objects of type Class, by executing a synchronized static method of that class. + /// Only one thread at a time can own an object's monitor. public final void notify(){ return; //TODO codavaj!! } - /** - * Wakes up all threads that are waiting on this object's monitor. A thread waits on an object's monitor by calling one of the wait methods. - * The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object. - * This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. - */ + /// Wakes up all threads that are waiting on this object's monitor. A thread waits on an object's monitor by calling one of the wait methods. + /// The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object. + /// This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. public final void notifyAll(){ return; //TODO codavaj!! } - /** - * Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. - * The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: - * getClass().getName() + '@' + Integer.toHexString(hashCode()) - */ + /// Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. + /// The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: + /// getClass().getName() + '@' + Integer.toHexString(hashCode()) public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Causes current thread to wait until another thread invokes the - * method or the - * method for this object. In other word's this method behaves exactly as if it simply performs the call wait(0). - * The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The thread then waits until it can re-obtain ownership of the monitor and resumes execution. - * This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. - */ + /// Causes current thread to wait until another thread invokes the + /// method or the + /// method for this object. In other word's this method behaves exactly as if it simply performs the call wait(0). + /// The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The thread then waits until it can re-obtain ownership of the monitor and resumes execution. + /// This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. public final void wait() throws java.lang.InterruptedException{ return; //TODO codavaj!! } - /** - * Causes current thread to wait until either another thread invokes the - * method or the - * method for this object, or a specified amount of time has elapsed. - * The current thread must own this object's monitor. - * This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens: Some other thread invokes the notify method for this object and thread T happens to be arbitrarily chosen as the thread to be awakened. Some other thread invokes the notifyAll method for this object. Some other thread interrupts thread T. The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified. - * The thread T is then removed from the wait set for this object and re-enabled for thread scheduling. It then competes in the usual manner with other threads for the right to synchronize on the object; once it has gained control of the object, all its synchronization claims on the object are restored to the status quo ante - that is, to the situation as of the time that the wait method was invoked. Thread T then returns from the invocation of the wait method. Thus, on return from the wait method, the synchronization state of the object and of thread T is exactly as it was when the wait method was invoked. - * If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above. - * Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits. - * This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. - */ + /// Causes current thread to wait until either another thread invokes the + /// method or the + /// method for this object, or a specified amount of time has elapsed. + /// The current thread must own this object's monitor. + /// This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens: Some other thread invokes the notify method for this object and thread T happens to be arbitrarily chosen as the thread to be awakened. Some other thread invokes the notifyAll method for this object. Some other thread interrupts thread T. The specified amount of real time has elapsed, more or less. If timeout is zero, however, then real time is not taken into consideration and the thread simply waits until notified. + /// The thread T is then removed from the wait set for this object and re-enabled for thread scheduling. It then competes in the usual manner with other threads for the right to synchronize on the object; once it has gained control of the object, all its synchronization claims on the object are restored to the status quo ante - that is, to the situation as of the time that the wait method was invoked. Thread T then returns from the invocation of the wait method. Thus, on return from the wait method, the synchronization state of the object and of thread T is exactly as it was when the wait method was invoked. + /// If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above. + /// Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits. + /// This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. public final void wait(long timeout) throws java.lang.InterruptedException{ return; //TODO codavaj!! } - /** - * Causes current thread to wait until another thread invokes the - * method or the - * method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. - * This method is similar to the wait method of one argument, but it allows finer control over the amount of time to wait for a notification before giving up. The amount of real time, measured in nanoseconds, is given by: - * 1000000*timeout+nanos - * In all other respects, this method does the same thing as the method wait(long) of one argument. In particular, wait(0, 0) means the same thing as wait(0). - * The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred: Another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The timeout period, specified by timeout milliseconds plus nanos nanoseconds arguments, has elapsed. - * The thread then waits until it can re-obtain ownership of the monitor and resumes execution - * This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. - */ + /// Causes current thread to wait until another thread invokes the + /// method or the + /// method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. + /// This method is similar to the wait method of one argument, but it allows finer control over the amount of time to wait for a notification before giving up. The amount of real time, measured in nanoseconds, is given by: + /// 1000000*timeout+nanos + /// In all other respects, this method does the same thing as the method wait(long) of one argument. In particular, wait(0, 0) means the same thing as wait(0). + /// The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred: Another thread notifies threads waiting on this object's monitor to wake up either through a call to the notify method or the notifyAll method. The timeout period, specified by timeout milliseconds plus nanos nanoseconds arguments, has elapsed. + /// The thread then waits until it can re-obtain ownership of the monitor and resumes execution + /// This method should only be called by a thread that is the owner of this object's monitor. See the notify method for a description of the ways in which a thread can become the owner of a monitor. public final void wait(long timeout, int nanos) throws java.lang.InterruptedException{ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/OutOfMemoryError.java b/Ports/CLDC11/src/java/lang/OutOfMemoryError.java index a8195bb71b..f480365981 100644 --- a/Ports/CLDC11/src/java/lang/OutOfMemoryError.java +++ b/Ports/CLDC11/src/java/lang/OutOfMemoryError.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown when the Java Virtual Machine cannot allocate an object because it is out of memory, and no more memory could be made available by the garbage collector. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown when the Java Virtual Machine cannot allocate an object because it is out of memory, and no more memory could be made available by the garbage collector. +/// Since: JDK1.0, CLDC 1.0 public class OutOfMemoryError extends java.lang.VirtualMachineError{ - /** - * Constructs an OutOfMemoryError with no detail message. - */ + /// Constructs an OutOfMemoryError with no detail message. public OutOfMemoryError(){ //TODO codavaj!! } - /** - * Constructs an OutOfMemoryError with the specified detail message. - * s - the detail message. - */ + /// Constructs an OutOfMemoryError with the specified detail message. + /// s - the detail message. public OutOfMemoryError(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Override.java b/Ports/CLDC11/src/java/lang/Override.java index 1d92a0d38a..af04f6f6d9 100644 --- a/Ports/CLDC11/src/java/lang/Override.java +++ b/Ports/CLDC11/src/java/lang/Override.java @@ -21,15 +21,13 @@ import java.lang.annotation.Target; import java.lang.annotation.ElementType; -/** - *

- * An annotation to indicate that a method is intended to override a superclass - * method. This provides a compile-time assertion that a method actually - * overrides the superclass method. - *

- * - * @since 1.5 - */ +/// An annotation to indicate that a method is intended to override a superclass +/// method. This provides a compile-time assertion that a method actually +/// overrides the superclass method. +/// +/// #### Since +/// +/// 1.5 @Target(ElementType.METHOD) @Retention(RetentionPolicy.SOURCE) public @interface Override { diff --git a/Ports/CLDC11/src/java/lang/Record.java b/Ports/CLDC11/src/java/lang/Record.java index d870566c2b..811a88b225 100644 --- a/Ports/CLDC11/src/java/lang/Record.java +++ b/Ports/CLDC11/src/java/lang/Record.java @@ -22,9 +22,7 @@ */ package java.lang; -/** - * Base class for Java record types. - */ +/// Base class for Java record types. public abstract class Record { protected Record() { } diff --git a/Ports/CLDC11/src/java/lang/Runnable.java b/Ports/CLDC11/src/java/lang/Runnable.java index 85b8e4d769..2a00345ebc 100644 --- a/Ports/CLDC11/src/java/lang/Runnable.java +++ b/Ports/CLDC11/src/java/lang/Runnable.java @@ -22,17 +22,13 @@ * have any questions. */ package java.lang; -/** - * The Runnable interface should be implemented by any class whose instances are intended to be executed by a thread. The class must define a method of no arguments called run. - * This interface is designed to provide a common protocol for objects that wish to execute code while they are active. For example, Runnable is implemented by class Thread. Being active simply means that a thread has been started and has not yet been stopped. - * In addition, Runnable provides the means for a class to be active while not subclassing Thread. A class that implements Runnable can run without subclassing Thread by instantiating a Thread instance and passing itself in as the target. In most cases, the Runnable interface should be used if you are only planning to override the run() method and no other Thread methods. This is important because classes should not be subclassed unless the programmer intends on modifying or enhancing the fundamental behavior of the class. - * Since: JDK1.0, CLDC 1.0 See Also:Thread - */ +/// The Runnable interface should be implemented by any class whose instances are intended to be executed by a thread. The class must define a method of no arguments called run. +/// This interface is designed to provide a common protocol for objects that wish to execute code while they are active. For example, Runnable is implemented by class Thread. Being active simply means that a thread has been started and has not yet been stopped. +/// In addition, Runnable provides the means for a class to be active while not subclassing Thread. A class that implements Runnable can run without subclassing Thread by instantiating a Thread instance and passing itself in as the target. In most cases, the Runnable interface should be used if you are only planning to override the run() method and no other Thread methods. This is important because classes should not be subclassed unless the programmer intends on modifying or enhancing the fundamental behavior of the class. +/// Since: JDK1.0, CLDC 1.0 See Also:Thread public interface Runnable{ - /** - * When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread. - * The general contract of the method run is that it may take any action whatsoever. - */ + /// When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread. + /// The general contract of the method run is that it may take any action whatsoever. public abstract void run(); } diff --git a/Ports/CLDC11/src/java/lang/Runtime.java b/Ports/CLDC11/src/java/lang/Runtime.java index 90d733b758..9f9571703d 100644 --- a/Ports/CLDC11/src/java/lang/Runtime.java +++ b/Ports/CLDC11/src/java/lang/Runtime.java @@ -22,47 +22,35 @@ * have any questions. */ package java.lang; -/** - * Every Java application has a single instance of class Runtime that allows the application to interface with the environment in which the application is running. The current runtime can be obtained from the getRuntime method. - * An application cannot create its own instance of this class. - * Since: JDK1.0, CLDC 1.0 See Also:getRuntime() - */ +/// Every Java application has a single instance of class Runtime that allows the application to interface with the environment in which the application is running. The current runtime can be obtained from the getRuntime method. +/// An application cannot create its own instance of this class. +/// Since: JDK1.0, CLDC 1.0 See Also:getRuntime() public class Runtime{ - /** - * Terminates the currently running Java application. This method never returns normally. - * The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination. - */ + /// Terminates the currently running Java application. This method never returns normally. + /// The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination. public void exit(int status){ return; //TODO codavaj!! } - /** - * Returns the amount of free memory in the system. Calling the gc method may result in increasing the value returned by freeMemory. - */ + /// Returns the amount of free memory in the system. Calling the gc method may result in increasing the value returned by freeMemory. public long freeMemory(){ return 0l; //TODO codavaj!! } - /** - * Runs the garbage collector. Calling this method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made its best effort to recycle all discarded objects. - * The name gc stands for "garbage collector". The Java Virtual Machine performs this recycling process automatically as needed even if the gc method is not invoked explicitly. - * The method System.gc() is the conventional and convenient means of invoking this method. - */ + /// Runs the garbage collector. Calling this method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made its best effort to recycle all discarded objects. + /// The name gc stands for "garbage collector". The Java Virtual Machine performs this recycling process automatically as needed even if the gc method is not invoked explicitly. + /// The method System.gc() is the conventional and convenient means of invoking this method. public void gc(){ return; //TODO codavaj!! } - /** - * Returns the runtime object associated with the current Java application. Most of the methods of class Runtime are instance methods and must be invoked with respect to the current runtime object. - */ + /// Returns the runtime object associated with the current Java application. Most of the methods of class Runtime are instance methods and must be invoked with respect to the current runtime object. public static java.lang.Runtime getRuntime(){ return null; //TODO codavaj!! } - /** - * Returns the total amount of memory in the Java Virtual Machine. The value returned by this method may vary over time, depending on the host environment. - * Note that the amount of memory required to hold an object of any given type may be implementation-dependent. - */ + /// Returns the total amount of memory in the Java Virtual Machine. The value returned by this method may vary over time, depending on the host environment. + /// Note that the amount of memory required to hold an object of any given type may be implementation-dependent. public long totalMemory(){ return 0l; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/RuntimeException.java b/Ports/CLDC11/src/java/lang/RuntimeException.java index a2c5b1f67e..8afd70d146 100644 --- a/Ports/CLDC11/src/java/lang/RuntimeException.java +++ b/Ports/CLDC11/src/java/lang/RuntimeException.java @@ -22,40 +22,33 @@ * have any questions. */ package java.lang; -/** - * RuntimeException is the superclass of those exceptions that can be thrown during the normal operation of the Java Virtual Machine. - * A method is not required to declare in its throws clause any subclasses of RuntimeException that might be thrown during the execution of the method but not caught. - * Since: JDK1.0, CLDC 1.0 - */ +/// RuntimeException is the superclass of those exceptions that can be thrown during the normal operation of the Java Virtual Machine. +/// A method is not required to declare in its throws clause any subclasses of RuntimeException that might be thrown during the execution of the method but not caught. +/// Since: JDK1.0, CLDC 1.0 public class RuntimeException extends java.lang.Exception{ - /** - * Constructs a RuntimeException with no detail message. - */ + /// Constructs a RuntimeException with no detail message. public RuntimeException(){ //TODO codavaj!! } - /** - * Constructs a RuntimeException with the specified detail message. - * s - the detail message. - */ + /// Constructs a RuntimeException with the specified detail message. + /// s - the detail message. public RuntimeException(java.lang.String s){ //TODO codavaj!! } - /** - * Constructs a RuntimeException with specified cause. - * @param cause The cause of the exception. - */ + /// Constructs a RuntimeException with specified cause. + /// + /// #### Parameters + /// + /// - `cause`: The cause of the exception. public RuntimeException(Throwable cause) { //TODO codavaj!! } - /** - * Constructs a RuntimeException with the specified detail message and cause. - * s - the detail message. - * cause The cause of the exception. - */ + /// Constructs a RuntimeException with the specified detail message and cause. + /// s - the detail message. + /// cause The cause of the exception. public RuntimeException(java.lang.String s, Throwable cause) { //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/SecurityException.java b/Ports/CLDC11/src/java/lang/SecurityException.java index 287b89c3a5..f766217c73 100644 --- a/Ports/CLDC11/src/java/lang/SecurityException.java +++ b/Ports/CLDC11/src/java/lang/SecurityException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown by the system to indicate a security violation. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown by the system to indicate a security violation. +/// Since: JDK1.0, CLDC 1.0 public class SecurityException extends java.lang.RuntimeException{ - /** - * Constructs a SecurityException with no detail message. - */ + /// Constructs a SecurityException with no detail message. public SecurityException(){ //TODO codavaj!! } - /** - * Constructs a SecurityException with the specified detail message. - * s - the detail message. - */ + /// Constructs a SecurityException with the specified detail message. + /// s - the detail message. public SecurityException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Short.java b/Ports/CLDC11/src/java/lang/Short.java index 0e1eb02c2e..d2fd8c381a 100644 --- a/Ports/CLDC11/src/java/lang/Short.java +++ b/Ports/CLDC11/src/java/lang/Short.java @@ -22,78 +22,62 @@ * have any questions. */ package java.lang; -/** - * The Short class is the standard wrapper for short values. - * Since: JDK1.1, CLDC 1.0 - */ +/// The Short class is the standard wrapper for short values. +/// Since: JDK1.1, CLDC 1.0 public final class Short extends Number implements Comparable { - /** - * The maximum value a Short can have. - * See Also:Constant Field Values - */ + /// The maximum value a Short can have. + /// See Also:Constant Field Values public static final short MAX_VALUE=32767; - /** - * The minimum value a Short can have. - * See Also:Constant Field Values - */ + /// The minimum value a Short can have. + /// See Also:Constant Field Values public static final short MIN_VALUE=-32768; - /** - * Constructs a Short object initialized to the specified short value. - * value - the initial value of the Short - */ + /// Constructs a Short object initialized to the specified short value. + /// value - the initial value of the Short public Short(short value){ //TODO codavaj!! } - /** - * Compares this object to the specified object. - */ + /// Compares this object to the specified object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns a hashcode for this Short. - */ + /// Returns a hashcode for this Short. public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Assuming the specified String represents a short, returns that short's value. Throws an exception if the String cannot be parsed as a short. The radix is assumed to be 10. - */ + /// Assuming the specified String represents a short, returns that short's value. Throws an exception if the String cannot be parsed as a short. The radix is assumed to be 10. public static short parseShort(java.lang.String s) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Assuming the specified String represents a short, returns that short's value in the radix specified by the second argument. Throws an exception if the String cannot be parsed as a short. - */ + /// Assuming the specified String represents a short, returns that short's value in the radix specified by the second argument. Throws an exception if the String cannot be parsed as a short. public static short parseShort(java.lang.String s, int radix) throws java.lang.NumberFormatException{ return 0; //TODO codavaj!! } - /** - * Returns the value of this Short as a short. - */ + /// Returns the value of this Short as a short. public short shortValue(){ return 0; //TODO codavaj!! } - /** - * Returns a String object representing this Short's value. - */ + /// Returns a String object representing this Short's value. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Returns the object instance of i - * @param i the primitive - * @return object instance - */ + /// Returns the object instance of i + /// + /// #### Parameters + /// + /// - `i`: the primitive + /// + /// #### Returns + /// + /// object instance public static Short valueOf(short i) { return null; } diff --git a/Ports/CLDC11/src/java/lang/StackTraceElement.java b/Ports/CLDC11/src/java/lang/StackTraceElement.java index 7235667d94..3cbe8df948 100644 --- a/Ports/CLDC11/src/java/lang/StackTraceElement.java +++ b/Ports/CLDC11/src/java/lang/StackTraceElement.java @@ -22,10 +22,7 @@ */ package java.lang; -/** - * - * @author shannah - */ +/// @author shannah public class StackTraceElement { private String declaringClass; private String methodName; diff --git a/Ports/CLDC11/src/java/lang/String.java b/Ports/CLDC11/src/java/lang/String.java index a2cbfb89d1..994908742a 100644 --- a/Ports/CLDC11/src/java/lang/String.java +++ b/Ports/CLDC11/src/java/lang/String.java @@ -26,15 +26,13 @@ import java.nio.charset.Charset; import java.util.Comparator; -/** - * The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class. - * Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example: - * is equivalent to: - * Here are some more examples of how strings can be used: - * The class String includes methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, and for creating a copy of a string with all characters translated to uppercase or to lowercase. - * The Java language provides special support for the string concatenation operator (+), and for conversion of other objects to strings. String concatenation is implemented through the StringBuffer class and its append method. String conversions are implemented through the method toString, defined by Object and inherited by all classes in Java. For additional information on string concatenation and conversion, see Gosling, Joy, and Steele, The Java Language Specification. - * Since: JDK1.0, CLDC 1.0 See Also:Object.toString(), StringBuffer, StringBuffer.append(boolean), StringBuffer.append(char), StringBuffer.append(char[]), StringBuffer.append(char[], int, int), StringBuffer.append(int), StringBuffer.append(long), StringBuffer.append(java.lang.Object), StringBuffer.append(java.lang.String) - */ +/// The String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class. +/// Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example: +/// is equivalent to: +/// Here are some more examples of how strings can be used: +/// The class String includes methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, and for creating a copy of a string with all characters translated to uppercase or to lowercase. +/// The Java language provides special support for the string concatenation operator (+), and for conversion of other objects to strings. String concatenation is implemented through the StringBuffer class and its append method. String conversions are implemented through the method toString, defined by Object and inherited by all classes in Java. For additional information on string concatenation and conversion, see Gosling, Joy, and Steele, The Java Language Specification. +/// Since: JDK1.0, CLDC 1.0 See Also:Object.toString(), StringBuffer, StringBuffer.append(boolean), StringBuffer.append(char), StringBuffer.append(char[]), StringBuffer.append(char[], int, int), StringBuffer.append(int), StringBuffer.append(long), StringBuffer.append(java.lang.Object), StringBuffer.append(java.lang.String) public final class String implements CharSequence, Comparable { public static final Comparator CASE_INSENSITIVE_ORDER = new Comparator() { @@ -42,93 +40,76 @@ public int compare(String o1, String o2){ return o1.compareToIgnoreCase(o2); } }; - /** - * Initializes a newly created String object so that it represents an empty character sequence. - */ + /// Initializes a newly created String object so that it represents an empty character sequence. public String(){ //TODO codavaj!! } - /** - * Construct a new String by converting the specified array of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. - * bytes - The bytes to be converted into characters - * JDK1.1 - */ + /// Construct a new String by converting the specified array of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. + /// bytes - The bytes to be converted into characters + /// JDK1.1 public String(byte[] bytes){ //TODO codavaj!! } - /** - * Construct a new String by converting the specified subarray of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray. - * bytes - The bytes to be converted into charactersoff - Index of the first byte to convertlen - Number of bytes to convert - * JDK1.1 - */ + /// Construct a new String by converting the specified subarray of bytes using the platform's default character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray. + /// bytes - The bytes to be converted into charactersoff - Index of the first byte to convertlen - Number of bytes to convert + /// JDK1.1 public String(byte[] bytes, int off, int len){ //TODO codavaj!! } - /** - * Construct a new String by converting the specified subarray of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray. - * bytes - The bytes to be converted into charactersoff - Index of the first byte to convertlen - Number of bytes to convertenc - The name of a character encoding - * - If the named encoding is not supported - * JDK1.1 - */ + /// Construct a new String by converting the specified subarray of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the subarray. + /// bytes - The bytes to be converted into charactersoff - Index of the first byte to convertlen - Number of bytes to convertenc - The name of a character encoding + /// - If the named encoding is not supported + /// JDK1.1 public String(byte[] bytes, int off, int len, java.lang.String enc) throws java.io.UnsupportedEncodingException{ //TODO codavaj!! } - /** - * Construct a new String by converting the specified array of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. - * bytes - The bytes to be converted into charactersenc - The name of a supported character encoding - * - If the named encoding is not supported - * @since 8.0 - */ + /// Construct a new String by converting the specified array of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. + /// bytes - The bytes to be converted into charactersenc - The name of a supported character encoding + /// - If the named encoding is not supported + /// + /// #### Since + /// + /// 8.0 public String(byte[] bytes, java.nio.charset.Charset charset) throws java.io.UnsupportedEncodingException { this(bytes, 0, bytes.length, charset.displayName()); } - /** - * Construct a new String by converting the specified array of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. - * bytes - The bytes to be converted into charactersenc - The name of a supported character encoding - * - If the named encoding is not supported - * JDK1.1 - */ + /// Construct a new String by converting the specified array of bytes using the specified character encoding. The length of the new String is a function of the encoding, and hence may not be equal to the length of the byte array. + /// bytes - The bytes to be converted into charactersenc - The name of a supported character encoding + /// - If the named encoding is not supported + /// JDK1.1 public String(byte[] bytes, java.lang.String enc) throws java.io.UnsupportedEncodingException{ //TODO codavaj!! } - /** - * Allocates a new String so that it represents the sequence of characters currently contained in the character array argument. The contents of the character array are copied; subsequent modification of the character array does not affect the newly created string. - * value - the initial value of the string. - * - if value is null. - */ + /// Allocates a new String so that it represents the sequence of characters currently contained in the character array argument. The contents of the character array are copied; subsequent modification of the character array does not affect the newly created string. + /// value - the initial value of the string. + /// - if value is null. public String(char[] value){ //TODO codavaj!! } - /** - * Allocates a new String that contains characters from a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string. - * value - array that is the source of characters.offset - the initial offset.count - the length. - * - if the offset and count arguments index characters outside the bounds of the value array. - * - if value is null. - */ + /// Allocates a new String that contains characters from a subarray of the character array argument. The offset argument is the index of the first character of the subarray and the count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string. + /// value - array that is the source of characters.offset - the initial offset.count - the length. + /// - if the offset and count arguments index characters outside the bounds of the value array. + /// - if value is null. public String(char[] value, int offset, int count){ //TODO codavaj!! } - /** - * Initializes a newly created String object so that it represents the same sequence of characters as the argument; in other words, the newly created string is a copy of the argument string. - * value - a String. - */ + /// Initializes a newly created String object so that it represents the same sequence of characters as the argument; in other words, the newly created string is a copy of the argument string. + /// value - a String. public String(java.lang.String value){ //TODO codavaj!! } - /** - * Allocates a new string that contains the sequence of characters currently contained in the string buffer argument. The contents of the string buffer are copied; subsequent modification of the string buffer does not affect the newly created string. - * buffer - a StringBuffer. - * - If buffer is null. - */ + /// Allocates a new string that contains the sequence of characters currently contained in the string buffer argument. The contents of the string buffer are copied; subsequent modification of the string buffer does not affect the newly created string. + /// buffer - a StringBuffer. + /// - If buffer is null. public String(java.lang.StringBuffer buffer){ //TODO codavaj!! } @@ -137,19 +118,15 @@ public String(java.lang.StringBuilder buffer) { //TODO codavaj!! } - /** - * Returns the character at the specified index. An index ranges from 0 to length() - 1. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing. - */ + /// Returns the character at the specified index. An index ranges from 0 to length() - 1. The first character of the sequence is at index 0, the next at index 1, and so on, as for array indexing. public char charAt(int index){ return ' '; //TODO codavaj!! } - /** - * Compares two strings lexicographically. The comparison is based on the Unicode value of each character in the strings. The character sequence represented by this String object is compared lexicographically to the character sequence represented by the argument string. The result is a negative integer if this String object lexicographically precedes the argument string. The result is a positive integer if this String object lexicographically follows the argument string. The result is zero if the strings are equal; compareTo returns 0 exactly when the - * method would return true. - * This is the definition of lexicographic ordering. If two strings are different, then either they have different characters at some index that is a valid index for both strings, or their lengths are different, or both. If they have different characters at one or more index positions, let k be the smallest such index; then the string whose character at position k has the smaller value, as determined by using the < operator, lexicographically precedes the other string. In this case, compareTo returns the difference of the two character values at position k in the two string -- that is, the value: - * this.charAt(k)-anotherString.charAt(k) If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case, compareTo returns the difference of the lengths of the strings -- that is, the value: this.length()-anotherString.length() - */ + /// Compares two strings lexicographically. The comparison is based on the Unicode value of each character in the strings. The character sequence represented by this String object is compared lexicographically to the character sequence represented by the argument string. The result is a negative integer if this String object lexicographically precedes the argument string. The result is a positive integer if this String object lexicographically follows the argument string. The result is zero if the strings are equal; compareTo returns 0 exactly when the + /// method would return true. + /// This is the definition of lexicographic ordering. If two strings are different, then either they have different characters at some index that is a valid index for both strings, or their lengths are different, or both. If they have different characters at one or more index positions, let k be the smallest such index; then the string whose character at position k has the smaller value, as determined by using the < operator, lexicographically precedes the other string. In this case, compareTo returns the difference of the two character values at position k in the two string -- that is, the value: + /// this.charAt(k)-anotherString.charAt(k) If there is no index position at which they differ, then the shorter string lexicographically precedes the longer string. In this case, compareTo returns the difference of the lengths of the strings -- that is, the value: this.length()-anotherString.length() public int compareTo(java.lang.String anotherString){ return 0; //TODO codavaj!! } @@ -174,176 +151,152 @@ public static String copyValueOf(char[] data, int offset, int count) { return null; } - /** - * Concatenates the specified string to the end of this string. - * If the length of the argument string is 0, then this String object is returned. Otherwise, a new String object is created, representing a character sequence that is the concatenation of the character sequence represented by this String object and the character sequence represented by the argument string. - * Examples: - * "cares".concat("s") returns "caress" "to".concat("get").concat("her") returns "together" - */ + /// Concatenates the specified string to the end of this string. + /// If the length of the argument string is 0, then this String object is returned. Otherwise, a new String object is created, representing a character sequence that is the concatenation of the character sequence represented by this String object and the character sequence represented by the argument string. + /// Examples: + /// "cares".concat("s") returns "caress" "to".concat("get").concat("her") returns "together" public java.lang.String concat(java.lang.String str){ return null; //TODO codavaj!! } - /** - * Tests if this string ends with the specified suffix. - */ + /// Tests if this string ends with the specified suffix. public boolean endsWith(java.lang.String suffix){ return false; //TODO codavaj!! } - /** - * Compares this string to the specified object. The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this object. - */ + /// Compares this string to the specified object. The result is true if and only if the argument is not null and is a String object that represents the same sequence of characters as this object. public boolean equals(java.lang.Object anObject){ return false; //TODO codavaj!! } - /** - * Compares this String to another String, ignoring case considerations. Two strings are considered equal ignoring case if they are of the same length, and corresponding characters in the two strings are equal ignoring case. - * Two characters c1 and c2 are considered the same, ignoring case if at least one of the following is true: The two characters are the same (as compared by the == operator). Applying the method Character.toUpperCase(char) to each character produces the same result. Applying the method Character.toLowerCase(char) to each character produces the same result. - */ + /// Compares this String to another String, ignoring case considerations. Two strings are considered equal ignoring case if they are of the same length, and corresponding characters in the two strings are equal ignoring case. + /// Two characters c1 and c2 are considered the same, ignoring case if at least one of the following is true: The two characters are the same (as compared by the == operator). Applying the method Character.toUpperCase(char) to each character produces the same result. Applying the method Character.toLowerCase(char) to each character produces the same result. public boolean equalsIgnoreCase(java.lang.String anotherString){ return false; //TODO codavaj!! } - /** - * Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array. - */ + /// Convert this String into bytes according to the platform's default character encoding, storing the result into a new byte array. public byte[] getBytes(){ return null; //TODO codavaj!! } - /** - * Convert this String into bytes according to the specified character encoding, storing the result into a new byte array. - */ + /// Convert this String into bytes according to the specified character encoding, storing the result into a new byte array. public byte[] getBytes(java.lang.String enc) throws java.io.UnsupportedEncodingException{ return null; //TODO codavaj!! } - /** - * Convert this String into bytes according to the specified character encoding, storing the result into a new byte array. - */ + /// Convert this String into bytes according to the specified character encoding, storing the result into a new byte array. public byte[] getBytes(Charset charset) throws java.io.UnsupportedEncodingException { return getBytes(charset.displayName()); } - /** - * Copies characters from this string into the destination character array. - * The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index: - * dstbegin + (srcEnd-srcBegin) - 1 - */ + /// Copies characters from this string into the destination character array. + /// The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1 (thus the total number of characters to be copied is srcEnd-srcBegin). The characters are copied into the subarray of dst starting at index dstBegin and ending at index: + /// dstbegin + (srcEnd-srcBegin) - 1 public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin){ return; //TODO codavaj!! } - /** - * Returns a hashcode for this string. The hashcode for a String object is computed as s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] using int arithmetic, where s[i] is the - * th character of the string, n is the length of the string, and ^ indicates exponentiation. (The hash value of the empty string is zero.) - */ + /// Returns a hashcode for this string. The hashcode for a String object is computed as s[0]*31^(n-1) + s[1]*31^(n-2) + ... + s[n-1] using int arithmetic, where s[i] is the + /// th character of the string, n is the length of the string, and ^ indicates exponentiation. (The hash value of the empty string is zero.) public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Returns the index within this string of the first occurrence of the specified character. If a character with value ch occurs in the character sequence represented by this String object, then the index of the first such occurrence is returned -- that is, the smallest value - * such that: this.charAt( - * ) == ch is true. If no such character occurs in this string, then -1 is returned. - */ + /// Returns the index within this string of the first occurrence of the specified character. If a character with value ch occurs in the character sequence represented by this String object, then the index of the first such occurrence is returned -- that is, the smallest value + /// such that: this.charAt( + /// ) == ch is true. If no such character occurs in this string, then -1 is returned. public int indexOf(int ch){ return 0; //TODO codavaj!! } - /** - * Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index. - * If a character with value ch occurs in the character sequence represented by this String object at an index no smaller than fromIndex, then the index of the first such occurrence is returned--that is, the smallest value k such that: - * (this.charAt( - * ) == ch) && ( - * >= fromIndex) is true. If no such character occurs in this string at or after position fromIndex, then -1 is returned. - * There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned. - */ + /// Returns the index within this string of the first occurrence of the specified character, starting the search at the specified index. + /// If a character with value ch occurs in the character sequence represented by this String object at an index no smaller than fromIndex, then the index of the first such occurrence is returned--that is, the smallest value k such that: + /// (this.charAt( + /// ) == ch) && ( + /// >= fromIndex) is true. If no such character occurs in this string at or after position fromIndex, then -1 is returned. + /// There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned. public int indexOf(int ch, int fromIndex){ return 0; //TODO codavaj!! } - /** - * Returns the index within this string of the first occurrence of the specified substring. The integer returned is the smallest value - * such that: this.startsWith(str, - * ) is true. - */ + /// Returns the index within this string of the first occurrence of the specified substring. The integer returned is the smallest value + /// such that: this.startsWith(str, + /// ) is true. public int indexOf(java.lang.String str){ return 0; //TODO codavaj!! } - /** - * Returns the index within this string of the first occurrence of the specified substring, starting at the specified index. The integer returned is the smallest value - * such that: this.startsWith(str, - * ) && ( - * >= fromIndex) is true. - * There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned. - */ + /// Returns the index within this string of the first occurrence of the specified substring, starting at the specified index. The integer returned is the smallest value + /// such that: this.startsWith(str, + /// ) && ( + /// >= fromIndex) is true. + /// There is no restriction on the value of fromIndex. If it is negative, it has the same effect as if it were zero: this entire string may be searched. If it is greater than the length of this string, it has the same effect as if it were equal to the length of this string: -1 is returned. public int indexOf(java.lang.String str, int fromIndex){ return 0; //TODO codavaj!! } - /** - * Returns a canonical representation for the string object. - * A pool of strings, initially empty, is maintained privately by the class String. - * When the intern method is invoked, if the pool already contains a string equal to this String object as determined by the equals(Object) method, then the string from the pool is returned. Otherwise, this String object is added to the pool and a reference to this String object is returned. - * It follows that for any two strings s and t, s.intern()==t.intern() is true if and only if s.equals(t) is true. - * All literal strings and string-valued constant expressions are interned. String literals are defined in Section 3.10.5 of the Java Language Specification - */ + /// Returns a canonical representation for the string object. + /// A pool of strings, initially empty, is maintained privately by the class String. + /// When the intern method is invoked, if the pool already contains a string equal to this String object as determined by the equals(Object) method, then the string from the pool is returned. Otherwise, this String object is added to the pool and a reference to this String object is returned. + /// It follows that for any two strings s and t, s.intern()==t.intern() is true if and only if s.equals(t) is true. + /// All literal strings and string-valued constant expressions are interned. String literals are defined in Section 3.10.5 of the Java Language Specification public java.lang.String intern(){ return null; //TODO codavaj!! } - /** - * Returns the index within this string of the last occurrence of the specified character. That is, the index returned is the largest value - * such that: this.charAt( - * ) == ch is true. The String is searched backwards starting at the last character. - */ + /// Returns the index within this string of the last occurrence of the specified character. That is, the index returned is the largest value + /// such that: this.charAt( + /// ) == ch is true. The String is searched backwards starting at the last character. public int lastIndexOf(int ch){ return 0; //TODO codavaj!! } - /** - * Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index. That is, the index returned is the largest value - * such that: (this.charAt(k) == ch) && (k <= fromIndex) is true. - */ + /// Returns the index within this string of the last occurrence of the specified character, searching backward starting at the specified index. That is, the index returned is the largest value + /// such that: (this.charAt(k) == ch) && (k <= fromIndex) is true. public int lastIndexOf(int ch, int fromIndex){ return 0; //TODO codavaj!! } - /** - * Searches in this string for the last index of the specified string. The - * search for the string starts at the end and moves towards the beginning - * of this string. - * - * @param string - * the string to find. - * @return the index of the first character of the specified string in this - * string, -1 if the specified string is not a substring. - * @throws NullPointerException - * if {@code string} is {@code null}. - */ + /// Searches in this string for the last index of the specified string. The + /// search for the string starts at the end and moves towards the beginning + /// of this string. + /// + /// #### Parameters + /// + /// - `string`: the string to find. + /// + /// #### Returns + /// + /// @return the index of the first character of the specified string in this + /// string, -1 if the specified string is not a substring. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `string` is `null`. public int lastIndexOf(String string) { // Use count instead of count - 1 so lastIndexOf("") answers count return lastIndexOf(string, length()); } - /** - * Searches in this string for the index of the specified string. The search - * for the string starts at the specified offset and moves towards the - * beginning of this string. - * - * @param subString - * the string to find. - * @param start - * the starting offset. - * @return the index of the first character of the specified string in this - * string , -1 if the specified string is not a substring. - * @throws NullPointerException - * if {@code subString} is {@code null}. - */ + /// Searches in this string for the index of the specified string. The search + /// for the string starts at the specified offset and moves towards the + /// beginning of this string. + /// + /// #### Parameters + /// + /// - `subString`: the string to find. + /// + /// - `start`: the starting offset. + /// + /// #### Returns + /// + /// @return the index of the first character of the specified string in this + /// string , -1 if the specified string is not a substring. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `subString` is `null`. public int lastIndexOf(String subString, int start) { int count = length(); int subCount = subString.length(); @@ -378,89 +331,67 @@ public int lastIndexOf(String subString, int start) { } - /** - * Returns the length of this string. The length is equal to the number of 16-bit Unicode characters in the string. - */ + /// Returns the length of this string. The length is equal to the number of 16-bit Unicode characters in the string. public int length(){ return 0; //TODO codavaj!! } - /** - * Tests if two string regions are equal. - * A substring of this String object is compared to a substring of the argument other. The result is true if these substrings represent character sequences that are the same, ignoring case if and only if ignoreCase is true. The substring of this String object to be compared begins at index toffset and has length len. The substring of other to be compared begins at index ooffset and has length len. The result is false if and only if at least one of the following is true: toffset is negative. ooffset is negative. toffset+len is greater than the length of this String object. ooffset+len is greater than the length of the other argument. There is some nonnegative integer k less than len such that: - * this.charAt(toffset+k) != other.charAt(ooffset+k) ignoreCase is true and there is some nonnegative integer - * less than len such that: Character.toLowerCase(this.charAt(toffset+k)) != Character.toLowerCase(other.charAt(ooffset+k)) and: Character.toUpperCase(this.charAt(toffset+k)) != Character.toUpperCase(other.charAt(ooffset+k)) - */ + /// Tests if two string regions are equal. + /// A substring of this String object is compared to a substring of the argument other. The result is true if these substrings represent character sequences that are the same, ignoring case if and only if ignoreCase is true. The substring of this String object to be compared begins at index toffset and has length len. The substring of other to be compared begins at index ooffset and has length len. The result is false if and only if at least one of the following is true: toffset is negative. ooffset is negative. toffset+len is greater than the length of this String object. ooffset+len is greater than the length of the other argument. There is some nonnegative integer k less than len such that: + /// this.charAt(toffset+k) != other.charAt(ooffset+k) ignoreCase is true and there is some nonnegative integer + /// less than len such that: Character.toLowerCase(this.charAt(toffset+k)) != Character.toLowerCase(other.charAt(ooffset+k)) and: Character.toUpperCase(this.charAt(toffset+k)) != Character.toUpperCase(other.charAt(ooffset+k)) public boolean regionMatches(boolean ignoreCase, int toffset, java.lang.String other, int ooffset, int len){ return false; //TODO codavaj!! } - /** - * Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar. - * If the character oldChar does not occur in the character sequence represented by this String object, then a reference to this String object is returned. Otherwise, a new String object is created that represents a character sequence identical to the character sequence represented by this String object, except that every occurrence of oldChar is replaced by an occurrence of newChar. - * Examples: - * "mesquite in your cellar".replace('e', 'o') returns "mosquito in your collar" "the war of baronets".replace('r', 'y') returns "the way of bayonets" "sparring with a purple porpoise".replace('p', 't') returns "starring with a turtle tortoise" "JonL".replace('q', 'x') returns "JonL" (no change) - */ + /// Returns a new string resulting from replacing all occurrences of oldChar in this string with newChar. + /// If the character oldChar does not occur in the character sequence represented by this String object, then a reference to this String object is returned. Otherwise, a new String object is created that represents a character sequence identical to the character sequence represented by this String object, except that every occurrence of oldChar is replaced by an occurrence of newChar. + /// Examples: + /// "mesquite in your cellar".replace('e', 'o') returns "mosquito in your collar" "the war of baronets".replace('r', 'y') returns "the way of bayonets" "sparring with a purple porpoise".replace('p', 't') returns "starring with a turtle tortoise" "JonL".replace('q', 'x') returns "JonL" (no change) public java.lang.String replace(char oldChar, char newChar){ return null; //TODO codavaj!! } - /** - * Tests if this string starts with the specified prefix. - */ + /// Tests if this string starts with the specified prefix. public boolean startsWith(java.lang.String prefix){ return false; //TODO codavaj!! } - /** - * Tests if this string starts with the specified prefix beginning at the specified index. - */ + /// Tests if this string starts with the specified prefix beginning at the specified index. public boolean startsWith(java.lang.String prefix, int toffset){ return false; //TODO codavaj!! } - /** - * Returns a new string that is a substring of this string. The substring begins with the character at the specified index and extends to the end of this string. - * Examples: - * "unhappy".substring(2) returns "happy" "Harbison".substring(3) returns "bison" "emptiness".substring(9) returns "" (an empty string) - */ + /// Returns a new string that is a substring of this string. The substring begins with the character at the specified index and extends to the end of this string. + /// Examples: + /// "unhappy".substring(2) returns "happy" "Harbison".substring(3) returns "bison" "emptiness".substring(9) returns "" (an empty string) public java.lang.String substring(int beginIndex){ return null; //TODO codavaj!! } - /** - * Returns a new string that is a substring of this string. The substring begins at the specified beginIndex and extends to the character at index endIndex - 1. Thus the length of the substring is endIndex-beginIndex. - * Examples: - * "hamburger".substring(4, 8) returns "urge" "smiles".substring(1, 5) returns "mile" - */ + /// Returns a new string that is a substring of this string. The substring begins at the specified beginIndex and extends to the character at index endIndex - 1. Thus the length of the substring is endIndex-beginIndex. + /// Examples: + /// "hamburger".substring(4, 8) returns "urge" "smiles".substring(1, 5) returns "mile" public java.lang.String substring(int beginIndex, int endIndex){ return null; //TODO codavaj!! } - /** - * Converts this string to a new character array. - */ + /// Converts this string to a new character array. public char[] toCharArray(){ return null; //TODO codavaj!! } - /** - * Converts all of the characters in this String to lower case. - */ + /// Converts all of the characters in this String to lower case. public java.lang.String toLowerCase(){ return null; //TODO codavaj!! } - /** - * This object (which is already a string!) is itself returned. - */ + /// This object (which is already a string!) is itself returned. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Converts all of the characters in this String to upper case. - */ + /// Converts all of the characters in this String to upper case. public java.lang.String toUpperCase(){ return null; //TODO codavaj!! } @@ -469,27 +400,21 @@ public java.lang.String toUpperCase(java.util.Locale locale) { return null; //TODO codavaj!! } - /** - * Removes white space from both ends of this string. - * If this String object represents an empty character sequence, or the first and last characters of character sequence represented by this String object both have codes greater than 'u0020' (the space character), then a reference to this String object is returned. - * Otherwise, if there is no character with a code greater than 'u0020' in the string, then a new String object representing an empty string is created and returned. - * Otherwise, let k be the index of the first character in the string whose code is greater than 'u0020', and let m be the index of the last character in the string whose code is greater than 'u0020'. A new String object is created, representing the substring of this string that begins with the character at index k and ends with the character at index m-that is, the result of this.substring(k,m+1). - * This method may be used to trim whitespace from the beginning and end of a string; in fact, it trims all ASCII control characters as well. - */ + /// Removes white space from both ends of this string. + /// If this String object represents an empty character sequence, or the first and last characters of character sequence represented by this String object both have codes greater than 'u0020' (the space character), then a reference to this String object is returned. + /// Otherwise, if there is no character with a code greater than 'u0020' in the string, then a new String object representing an empty string is created and returned. + /// Otherwise, let k be the index of the first character in the string whose code is greater than 'u0020', and let m be the index of the last character in the string whose code is greater than 'u0020'. A new String object is created, representing the substring of this string that begins with the character at index k and ends with the character at index m-that is, the result of this.substring(k,m+1). + /// This method may be used to trim whitespace from the beginning and end of a string; in fact, it trims all ASCII control characters as well. public java.lang.String trim(){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the boolean argument. - */ + /// Returns the string representation of the boolean argument. public static java.lang.String valueOf(boolean b){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the char argument. - */ + /// Returns the string representation of the char argument. public static java.lang.String valueOf(char c){ return null; //TODO codavaj!! } @@ -498,49 +423,37 @@ java.lang.String valueOf(char[] data){ return null; //TODO codavaj!! } - /** - * Returns the string representation of a specific subarray of the char array argument. - * The offset argument is the index of the first character of the subarray. The count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string. - */ + /// Returns the string representation of a specific subarray of the char array argument. + /// The offset argument is the index of the first character of the subarray. The count argument specifies the length of the subarray. The contents of the subarray are copied; subsequent modification of the character array does not affect the newly created string. public static java.lang.String valueOf(char[] data, int offset, int count){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the double argument. - * The representation is exactly the one returned by the Double.toString method of one argument. - */ + /// Returns the string representation of the double argument. + /// The representation is exactly the one returned by the Double.toString method of one argument. public static java.lang.String valueOf(double d){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the float argument. - * The representation is exactly the one returned by the Float.toString method of one argument. - */ + /// Returns the string representation of the float argument. + /// The representation is exactly the one returned by the Float.toString method of one argument. public static java.lang.String valueOf(float f){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the int argument. - * The representation is exactly the one returned by the Integer.toString method of one argument. - */ + /// Returns the string representation of the int argument. + /// The representation is exactly the one returned by the Integer.toString method of one argument. public static java.lang.String valueOf(int i){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the long argument. - * The representation is exactly the one returned by the Long.toString method of one argument. - */ + /// Returns the string representation of the long argument. + /// The representation is exactly the one returned by the Long.toString method of one argument. public static java.lang.String valueOf(long l){ return null; //TODO codavaj!! } - /** - * Returns the string representation of the Object argument. - */ + /// Returns the string representation of the Object argument. public static java.lang.String valueOf(java.lang.Object obj){ return null; //TODO codavaj!! } @@ -553,40 +466,49 @@ public static String format(String format, Object... args) { return null; //TODO codavaj!! } - /** - * Checks if string contains the given char sequence. - * @param seq The charsequence to check - * @return True if seq is contained in string. - */ + /// Checks if string contains the given char sequence. + /// + /// #### Parameters + /// + /// - `seq`: The charsequence to check + /// + /// #### Returns + /// + /// True if seq is contained in string. public boolean contains(CharSequence seq) { return false; //TODO codavaj!! } - /** - * Checks if string is empty. - * @return True if string is empty - */ + /// Checks if string is empty. + /// + /// #### Returns + /// + /// True if string is empty public boolean isEmpty() { return false; //TODO codavaj!! } - /** - * Compares the specified string to this string and compares the specified - * range of characters to determine if they are the same. - * - * @param thisStart - * the starting offset in this string. - * @param string - * the string to compare. - * @param start - * the starting offset in the specified string. - * @param length - * the number of characters to compare. - * @return {@code true} if the ranges of characters are equal, {@code false} - * otherwise - * @throws NullPointerException - * if {@code string} is {@code null}. - */ + /// Compares the specified string to this string and compares the specified + /// range of characters to determine if they are the same. + /// + /// #### Parameters + /// + /// - `thisStart`: the starting offset in this string. + /// + /// - `string`: the string to compare. + /// + /// - `start`: the starting offset in the specified string. + /// + /// - `length`: the number of characters to compare. + /// + /// #### Returns + /// + /// @return `true` if the ranges of characters are equal, `false` + /// otherwise + /// + /// #### Throws + /// + /// - `NullPointerException`: if `string` is `null`. public boolean regionMatches(int thisStart, String string, int start, int length) { return false; } diff --git a/Ports/CLDC11/src/java/lang/StringBuffer.java b/Ports/CLDC11/src/java/lang/StringBuffer.java index 368a8986e0..38e02416a4 100644 --- a/Ports/CLDC11/src/java/lang/StringBuffer.java +++ b/Ports/CLDC11/src/java/lang/StringBuffer.java @@ -22,55 +22,43 @@ * have any questions. */ package java.lang; -/** - * A string buffer implements a mutable sequence of characters. A string buffer is like a String, but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls. - * String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved. - * String buffers are used by the compiler to implement the binary string concatenation operator +. For example, the code: - * is compiled to the equivalent of: - * The principal operations on a StringBuffer are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point. - * For example, if z refers to a string buffer object whose current contents are "start", then the method call z.append("le") would cause the string buffer to contain "startle", whereas z.insert(4, "le") would alter the string buffer to contain "starlet". - * In general, if sb refers to an instance of a StringBuffer, then sb.append(x) has the same effect as sb.insert(sb.length(),x). - * Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to allocate a new internal buffer array. If the internal buffer overflows, it is automatically made larger. - * Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, String - */ +/// A string buffer implements a mutable sequence of characters. A string buffer is like a String, but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls. +/// String buffers are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved. +/// String buffers are used by the compiler to implement the binary string concatenation operator +. For example, the code: +/// is compiled to the equivalent of: +/// The principal operations on a StringBuffer are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string buffer. The append method always adds these characters at the end of the buffer; the insert method adds the characters at a specified point. +/// For example, if z refers to a string buffer object whose current contents are "start", then the method call z.append("le") would cause the string buffer to contain "startle", whereas z.insert(4, "le") would alter the string buffer to contain "starlet". +/// In general, if sb refers to an instance of a StringBuffer, then sb.append(x) has the same effect as sb.insert(sb.length(),x). +/// Every string buffer has a capacity. As long as the length of the character sequence contained in the string buffer does not exceed the capacity, it is not necessary to allocate a new internal buffer array. If the internal buffer overflows, it is automatically made larger. +/// Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, String public final class StringBuffer implements CharSequence { - /** - * Constructs a string buffer with no characters in it and an initial capacity of 16 characters. - */ + /// Constructs a string buffer with no characters in it and an initial capacity of 16 characters. public StringBuffer(){ //TODO codavaj!! } - /** - * Constructs a string buffer with no characters in it and an initial capacity specified by the length argument. - * length - the initial capacity. - * - if the length argument is less than 0. - */ + /// Constructs a string buffer with no characters in it and an initial capacity specified by the length argument. + /// length - the initial capacity. + /// - if the length argument is less than 0. public StringBuffer(int length){ //TODO codavaj!! } - /** - * Constructs a string buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is 16 plus the length of the string argument. - * str - the initial contents of the buffer. - */ + /// Constructs a string buffer so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string buffer is a copy of the argument string. The initial capacity of the string buffer is 16 plus the length of the string argument. + /// str - the initial contents of the buffer. public StringBuffer(java.lang.String str){ //TODO codavaj!! } - /** - * Appends the string representation of the boolean argument to the string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the boolean argument to the string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(boolean b){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the char argument to this string buffer. - * The argument is appended to the contents of this string buffer. The length of this string buffer increases by 1. - * The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then appended to this StringBuffer object. - */ + /// Appends the string representation of the char argument to this string buffer. + /// The argument is appended to the contents of this string buffer. The length of this string buffer increases by 1. + /// The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then appended to this StringBuffer object. public java.lang.StringBuffer append(char c){ return null; //TODO codavaj!! } @@ -79,123 +67,93 @@ java.lang.StringBuffer append(char[] str){ return null; //TODO codavaj!! } - /** - * Appends the string representation of a subarray of the char array argument to this string buffer. - * Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of len. - * The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf(char[],int,int) and the characters of that string were then appended to this StringBuffer object. - */ + /// Appends the string representation of a subarray of the char array argument to this string buffer. + /// Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string buffer. The length of this string buffer increases by the value of len. + /// The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf(char[],int,int) and the characters of that string were then appended to this StringBuffer object. public java.lang.StringBuffer append(char[] str, int offset, int len){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the double argument to this string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the double argument to this string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(double d){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the float argument to this string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the float argument to this string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(float f){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the int argument to this string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the int argument to this string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(int i){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the long argument to this string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the long argument to this string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(long l){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the Object argument to this string buffer. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. - */ + /// Appends the string representation of the Object argument to this string buffer. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string buffer. public java.lang.StringBuffer append(java.lang.Object obj){ return null; //TODO codavaj!! } - /** - * Appends the string to this string buffer. - * The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are appended to this string buffer. - * Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str. - */ + /// Appends the string to this string buffer. + /// The characters of the String argument are appended, in order, to the contents of this string buffer, increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are appended to this string buffer. + /// Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str. public java.lang.StringBuffer append(java.lang.String str){ return null; //TODO codavaj!! } - /** - * Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur. - */ + /// Returns the current capacity of the String buffer. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur. public int capacity(){ return 0; //TODO codavaj!! } - /** - * The specified character of the sequence currently represented by the string buffer, as indicated by the index argument, is returned. The first character of a string buffer is at index 0, the next at index 1, and so on, for array indexing. - * The index argument must be greater than or equal to 0, and less than the length of this string buffer. - */ + /// The specified character of the sequence currently represented by the string buffer, as indicated by the index argument, is returned. The first character of a string buffer is at index 0, the next at index 1, and so on, for array indexing. + /// The index argument must be greater than or equal to 0, and less than the length of this string buffer. public char charAt(int index){ return ' '; //TODO codavaj!! } - /** - * Removes the characters in a substring of this StringBuffer. The substring begins at the specified start and extends to the character at index end - 1 or to the end of the StringBuffer if no such character exists. If start is equal to end, no changes are made. - */ + /// Removes the characters in a substring of this StringBuffer. The substring begins at the specified start and extends to the character at index end - 1 or to the end of the StringBuffer if no such character exists. If start is equal to end, no changes are made. public java.lang.StringBuffer delete(int start, int end){ return null; //TODO codavaj!! } - /** - * Removes the character at the specified position in this StringBuffer (shortening the StringBuffer by one character). - */ + /// Removes the character at the specified position in this StringBuffer (shortening the StringBuffer by one character). public java.lang.StringBuffer deleteCharAt(int index){ return null; //TODO codavaj!! } - /** - * Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: The minimumCapacity argument. Twice the old capacity, plus 2. If the minimumCapacity argument is nonpositive, this method takes no action and simply returns. - */ + /// Ensures that the capacity of the buffer is at least equal to the specified minimum. If the current capacity of this string buffer is less than the argument, then a new internal buffer is allocated with greater capacity. The new capacity is the larger of: The minimumCapacity argument. Twice the old capacity, plus 2. If the minimumCapacity argument is nonpositive, this method takes no action and simply returns. public void ensureCapacity(int minimumCapacity){ return; //TODO codavaj!! } - /** - * Characters are copied from this string buffer into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index: - * dstbegin + (srcEnd-srcBegin) - 1 - */ + /// Characters are copied from this string buffer into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index: + /// dstbegin + (srcEnd-srcBegin) - 1 public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin){ return; //TODO codavaj!! } - /** - * Inserts the string representation of the boolean argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the boolean argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, boolean b){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the char argument into this string buffer. - * The second argument is inserted into the contents of this string buffer at the position indicated by offset. The length of this string buffer increases by one. - * The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then inserted into this StringBuffer object at the position indicated by offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the char argument into this string buffer. + /// The second argument is inserted into the contents of this string buffer at the position indicated by offset. The length of this string buffer increases by one. + /// The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then inserted into this StringBuffer object at the position indicated by offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, char c){ return null; //TODO codavaj!! } @@ -204,101 +162,79 @@ java.lang.StringBuffer insert(int offset, char[] str){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the double argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the double argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, double d){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the float argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the float argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, float f){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the second int argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the second int argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, int i){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the long argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the position indicated by offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the long argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the position indicated by offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, long l){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the Object argument into this string buffer. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string representation of the Object argument into this string buffer. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string buffer at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, java.lang.Object obj){ return null; //TODO codavaj!! } - /** - * Inserts the string into this string buffer. - * The characters of the String argument are inserted, in order, into this string buffer at the indicated offset, moving up any characters originally above that position and increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are inserted into this string buffer. - * The character at index k in the new character sequence is equal to: the character at index k in the old character sequence, if k is less than offset the character at index k-offset in the argument str, if k is not less than offset but is less than offset+str.length() the character at index k-str.length() in the old character sequence, if k is not less than offset+str.length() - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. - */ + /// Inserts the string into this string buffer. + /// The characters of the String argument are inserted, in order, into this string buffer at the indicated offset, moving up any characters originally above that position and increasing the length of this string buffer by the length of the argument. If str is null, then the four characters "null" are inserted into this string buffer. + /// The character at index k in the new character sequence is equal to: the character at index k in the old character sequence, if k is less than offset the character at index k-offset in the argument str, if k is not less than offset but is less than offset+str.length() the character at index k-str.length() in the old character sequence, if k is not less than offset+str.length() + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string buffer. public java.lang.StringBuffer insert(int offset, java.lang.String str){ return null; //TODO codavaj!! } - /** - * Returns the length (character count) of this string buffer. - */ + /// Returns the length (character count) of this string buffer. public int length(){ return 0; //TODO codavaj!! } - /** - * The character sequence contained in this string buffer is replaced by the reverse of the sequence. - * Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence. - */ + /// The character sequence contained in this string buffer is replaced by the reverse of the sequence. + /// Let n be the length of the old character sequence, the one contained in the string buffer just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence. public java.lang.StringBuffer reverse(){ return null; //TODO codavaj!! } - /** - * The character at the specified index of this string buffer is set to ch. The string buffer is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index. - * The offset argument must be greater than or equal to 0, and less than the length of this string buffer. - */ + /// The character at the specified index of this string buffer is set to ch. The string buffer is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index. + /// The offset argument must be greater than or equal to 0, and less than the length of this string buffer. public void setCharAt(int index, char ch){ return; //TODO codavaj!! } - /** - * Sets the length of this string buffer. This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index - * less than newLength, the character at index - * in the new character sequence is the same as the character at index - * in the old sequence if - * is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. In other words, if the newLength argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the newLength argument. - * If the newLength argument is greater than or equal to the current length, sufficient null characters ('u0000') are appended to the string buffer so that length becomes the newLength argument. - * The newLength argument must be greater than or equal to 0. - */ + /// Sets the length of this string buffer. This string buffer is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index + /// less than newLength, the character at index + /// in the new character sequence is the same as the character at index + /// in the old sequence if + /// is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. In other words, if the newLength argument is less than the current length of the string buffer, the string buffer is truncated to contain exactly the number of characters given by the newLength argument. + /// If the newLength argument is greater than or equal to the current length, sufficient null characters ('u0000') are appended to the string buffer so that length becomes the newLength argument. + /// The newLength argument must be greater than or equal to 0. public void setLength(int newLength){ return; //TODO codavaj!! } - /** - * Converts to a string representing the data in this string buffer. A new String object is allocated and initialized to contain the character sequence currently represented by this string buffer. This String is then returned. Subsequent changes to the string buffer do not affect the contents of the String. - * Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string buffer. Any subsequent operation that alters the content or capacity of the string buffer must then make a copy of the internal buffer at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation when it is implemented using a string buffer. - */ + /// Converts to a string representing the data in this string buffer. A new String object is allocated and initialized to contain the character sequence currently represented by this string buffer. This String is then returned. Subsequent changes to the string buffer do not affect the contents of the String. + /// Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string buffer. Any subsequent operation that alters the content or capacity of the string buffer must then make a copy of the internal buffer at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation when it is implemented using a string buffer. public java.lang.String toString(){ return null; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/StringBuilder.java b/Ports/CLDC11/src/java/lang/StringBuilder.java index 9a06725392..f7d3ac90e1 100644 --- a/Ports/CLDC11/src/java/lang/StringBuilder.java +++ b/Ports/CLDC11/src/java/lang/StringBuilder.java @@ -22,55 +22,43 @@ * have any questions. */ package java.lang; -/** - * A string builder implements a mutable sequence of characters. A string builder is like a String, but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls. - * String builders are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved. - * String builders are used by the compiler to implement the binary string concatenation operator +. For example, the code: - * is compiled to the equivalent of: - * The principal operations on a StringBuilder are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string builder. The append method always adds these characters at the end of the builder; the insert method adds the characters at a specified point. - * For example, if z refers to a string builder object whose current contents are "start", then the method call z.append("le") would cause the string builder to contain "startle", whereas z.insert(4, "le") would alter the string builder to contain "starlet". - * In general, if sb refers to an instance of a StringBuilder, then sb.append(x) has the same effect as sb.insert(sb.length(),x). - * Every string builder has a capacity. As long as the length of the character sequence contained in the string builder does not exceed the capacity, it is not necessary to allocate a new internal builder array. If the internal builder overflows, it is automatically made larger. - * Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, String - */ +/// A string builder implements a mutable sequence of characters. A string builder is like a String, but can be modified. At any point in time it contains some particular sequence of characters, but the length and content of the sequence can be changed through certain method calls. +/// String builders are safe for use by multiple threads. The methods are synchronized where necessary so that all the operations on any particular instance behave as if they occur in some serial order that is consistent with the order of the method calls made by each of the individual threads involved. +/// String builders are used by the compiler to implement the binary string concatenation operator +. For example, the code: +/// is compiled to the equivalent of: +/// The principal operations on a StringBuilder are the append and insert methods, which are overloaded so as to accept data of any type. Each effectively converts a given datum to a string and then appends or inserts the characters of that string to the string builder. The append method always adds these characters at the end of the builder; the insert method adds the characters at a specified point. +/// For example, if z refers to a string builder object whose current contents are "start", then the method call z.append("le") would cause the string builder to contain "startle", whereas z.insert(4, "le") would alter the string builder to contain "starlet". +/// In general, if sb refers to an instance of a StringBuilder, then sb.append(x) has the same effect as sb.insert(sb.length(),x). +/// Every string builder has a capacity. As long as the length of the character sequence contained in the string builder does not exceed the capacity, it is not necessary to allocate a new internal builder array. If the internal builder overflows, it is automatically made larger. +/// Since: JDK1.0, CLDC 1.0 See Also:ByteArrayOutputStream, String public final class StringBuilder implements CharSequence { - /** - * Constructs a string builder with no characters in it and an initial capacity of 16 characters. - */ + /// Constructs a string builder with no characters in it and an initial capacity of 16 characters. public StringBuilder(){ //TODO codavaj!! } - /** - * Constructs a string builder with no characters in it and an initial capacity specified by the length argument. - * length - the initial capacity. - * - if the length argument is less than 0. - */ + /// Constructs a string builder with no characters in it and an initial capacity specified by the length argument. + /// length - the initial capacity. + /// - if the length argument is less than 0. public StringBuilder(int length){ //TODO codavaj!! } - /** - * Constructs a string builder so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string builder is a copy of the argument string. The initial capacity of the string builder is 16 plus the length of the string argument. - * str - the initial contents of the builder. - */ + /// Constructs a string builder so that it represents the same sequence of characters as the string argument; in other words, the initial contents of the string builder is a copy of the argument string. The initial capacity of the string builder is 16 plus the length of the string argument. + /// str - the initial contents of the builder. public StringBuilder(java.lang.String str){ //TODO codavaj!! } - /** - * Appends the string representation of the boolean argument to the string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the boolean argument to the string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(boolean b){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the char argument to this string builder. - * The argument is appended to the contents of this string builder. The length of this string builder increases by 1. - * The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then appended to this StringBuilder object. - */ + /// Appends the string representation of the char argument to this string builder. + /// The argument is appended to the contents of this string builder. The length of this string builder increases by 1. + /// The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then appended to this StringBuilder object. public java.lang.StringBuilder append(char c){ return null; //TODO codavaj!! } @@ -79,132 +67,106 @@ public java.lang.StringBuilder append(char[] str){ return null; //TODO codavaj!! } - /** - * Appends the string representation of a subarray of the char array argument to this string builder. - * Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string builder. The length of this string builder increases by the value of len. - * The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf(char[],int,int) and the characters of that string were then appended to this StringBuilder object. - */ + /// Appends the string representation of a subarray of the char array argument to this string builder. + /// Characters of the character array str, starting at index offset, are appended, in order, to the contents of this string builder. The length of this string builder increases by the value of len. + /// The overall effect is exactly as if the arguments were converted to a string by the method String.valueOf(char[],int,int) and the characters of that string were then appended to this StringBuilder object. public java.lang.StringBuilder append(char[] str, int offset, int len){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the double argument to this string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the double argument to this string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(double d){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the float argument to this string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the float argument to this string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(float f){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the int argument to this string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the int argument to this string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(int i){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the long argument to this string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the long argument to this string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(long l){ return null; //TODO codavaj!! } - /** - * Appends the string representation of the Object argument to this string builder. - * The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. - */ + /// Appends the string representation of the Object argument to this string builder. + /// The argument is converted to a string as if by the method String.valueOf, and the characters of that string are then appended to this string builder. public java.lang.StringBuilder append(java.lang.Object obj){ return null; //TODO codavaj!! } - /** - * Appends the string to this string builder. - * The characters of the String argument are appended, in order, to the contents of this string builder, increasing the length of this string builder by the length of the argument. If str is null, then the four characters "null" are appended to this string builder. - * Let n be the length of the old character sequence, the one contained in the string builder just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str. - */ + /// Appends the string to this string builder. + /// The characters of the String argument are appended, in order, to the contents of this string builder, increasing the length of this string builder by the length of the argument. If str is null, then the four characters "null" are appended to this string builder. + /// Let n be the length of the old character sequence, the one contained in the string builder just prior to execution of the append method. Then the character at index k in the new character sequence is equal to the character at index k in the old character sequence, if k is less than n; otherwise, it is equal to the character at index k-n in the argument str. public java.lang.StringBuilder append(java.lang.String str){ return null; //TODO codavaj!! } - /** - * Returns the current capacity of the String builder. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur. - */ + /// Returns the current capacity of the String builder. The capacity is the amount of storage available for newly inserted characters; beyond which an allocation will occur. public int capacity(){ return 0; //TODO codavaj!! } - /** - * The specified character of the sequence currently represented by the string builder, as indicated by the index argument, is returned. The first character of a string builder is at index 0, the next at index 1, and so on, for array indexing. - * The index argument must be greater than or equal to 0, and less than the length of this string builder. - */ + /// The specified character of the sequence currently represented by the string builder, as indicated by the index argument, is returned. The first character of a string builder is at index 0, the next at index 1, and so on, for array indexing. + /// The index argument must be greater than or equal to 0, and less than the length of this string builder. public char charAt(int index){ return ' '; //TODO codavaj!! } - /** - * Removes the characters in a substring of this StringBuilder. The substring begins at the specified start and extends to the character at index end - 1 or to the end of the StringBuilder if no such character exists. If start is equal to end, no changes are made. - */ + /// Removes the characters in a substring of this StringBuilder. The substring begins at the specified start and extends to the character at index end - 1 or to the end of the StringBuilder if no such character exists. If start is equal to end, no changes are made. public java.lang.StringBuilder delete(int start, int end){ return null; //TODO codavaj!! } - /** - * Appends StringBuffer to end of builder. - * @param buf The string buffer to append - * @return Self for chaining. - */ + /// Appends StringBuffer to end of builder. + /// + /// #### Parameters + /// + /// - `buf`: The string buffer to append + /// + /// #### Returns + /// + /// Self for chaining. public java.lang.StringBuilder append(java.lang.StringBuffer buf){ return null; //TODO codavaj!! } - /** - * Removes the character at the specified position in this StringBuilder (shortening the StringBuilder by one character). - */ + /// Removes the character at the specified position in this StringBuilder (shortening the StringBuilder by one character). public java.lang.StringBuilder deleteCharAt(int index){ return null; //TODO codavaj!! } - /** - * Ensures that the capacity of the builder is at least equal to the specified minimum. If the current capacity of this string builder is less than the argument, then a new internal builder is allocated with greater capacity. The new capacity is the larger of: The minimumCapacity argument. Twice the old capacity, plus 2. If the minimumCapacity argument is nonpositive, this method takes no action and simply returns. - */ + /// Ensures that the capacity of the builder is at least equal to the specified minimum. If the current capacity of this string builder is less than the argument, then a new internal builder is allocated with greater capacity. The new capacity is the larger of: The minimumCapacity argument. Twice the old capacity, plus 2. If the minimumCapacity argument is nonpositive, this method takes no action and simply returns. public void ensureCapacity(int minimumCapacity){ return; //TODO codavaj!! } - /** - * Characters are copied from this string builder into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index: - * dstbegin + (srcEnd-srcBegin) - 1 - */ + /// Characters are copied from this string builder into the destination character array dst. The first character to be copied is at index srcBegin; the last character to be copied is at index srcEnd-1. The total number of characters to be copied is srcEnd-srcBegin. The characters are copied into the subarray of dst starting at index dstBegin and ending at index: + /// dstbegin + (srcEnd-srcBegin) - 1 public void getChars(int srcBegin, int srcEnd, char[] dst, int dstBegin){ return; //TODO codavaj!! } - /** - * Inserts the string representation of the boolean argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the boolean argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, boolean b){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the char argument into this string builder. - * The second argument is inserted into the contents of this string builder at the position indicated by offset. The length of this string builder increases by one. - * The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then inserted into this StringBuilder object at the position indicated by offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the char argument into this string builder. + /// The second argument is inserted into the contents of this string builder at the position indicated by offset. The length of this string builder increases by one. + /// The overall effect is exactly as if the argument were converted to a string by the method String.valueOf(char) and the character in that string were then inserted into this StringBuilder object at the position indicated by offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, char c){ return null; //TODO codavaj!! } @@ -213,101 +175,79 @@ java.lang.StringBuilder insert(int offset, char[] str){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the double argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the double argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, double d){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the float argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the float argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, float f){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the second int argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the second int argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, int i){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the long argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the position indicated by offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the long argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the position indicated by offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, long l){ return null; //TODO codavaj!! } - /** - * Inserts the string representation of the Object argument into this string builder. - * The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string representation of the Object argument into this string builder. + /// The second argument is converted to a string as if by the method String.valueOf, and the characters of that string are then inserted into this string builder at the indicated offset. + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, java.lang.Object obj){ return null; //TODO codavaj!! } - /** - * Inserts the string into this string builder. - * The characters of the String argument are inserted, in order, into this string builder at the indicated offset, moving up any characters originally above that position and increasing the length of this string builder by the length of the argument. If str is null, then the four characters "null" are inserted into this string builder. - * The character at index k in the new character sequence is equal to: the character at index k in the old character sequence, if k is less than offset the character at index k-offset in the argument str, if k is not less than offset but is less than offset+str.length() the character at index k-str.length() in the old character sequence, if k is not less than offset+str.length() - * The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. - */ + /// Inserts the string into this string builder. + /// The characters of the String argument are inserted, in order, into this string builder at the indicated offset, moving up any characters originally above that position and increasing the length of this string builder by the length of the argument. If str is null, then the four characters "null" are inserted into this string builder. + /// The character at index k in the new character sequence is equal to: the character at index k in the old character sequence, if k is less than offset the character at index k-offset in the argument str, if k is not less than offset but is less than offset+str.length() the character at index k-str.length() in the old character sequence, if k is not less than offset+str.length() + /// The offset argument must be greater than or equal to 0, and less than or equal to the length of this string builder. public java.lang.StringBuilder insert(int offset, java.lang.String str){ return null; //TODO codavaj!! } - /** - * Returns the length (character count) of this string builder. - */ + /// Returns the length (character count) of this string builder. public int length(){ return 0; //TODO codavaj!! } - /** - * The character sequence contained in this string builder is replaced by the reverse of the sequence. - * Let n be the length of the old character sequence, the one contained in the string builder just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence. - */ + /// The character sequence contained in this string builder is replaced by the reverse of the sequence. + /// Let n be the length of the old character sequence, the one contained in the string builder just prior to execution of the reverse method. Then the character at index k in the new character sequence is equal to the character at index n-k-1 in the old character sequence. public java.lang.StringBuilder reverse(){ return null; //TODO codavaj!! } - /** - * The character at the specified index of this string builder is set to ch. The string builder is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index. - * The offset argument must be greater than or equal to 0, and less than the length of this string builder. - */ + /// The character at the specified index of this string builder is set to ch. The string builder is altered to represent a new character sequence that is identical to the old character sequence, except that it contains the character ch at position index. + /// The offset argument must be greater than or equal to 0, and less than the length of this string builder. public void setCharAt(int index, char ch){ return; //TODO codavaj!! } - /** - * Sets the length of this string builder. This string builder is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index - * less than newLength, the character at index - * in the new character sequence is the same as the character at index - * in the old sequence if - * is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. In other words, if the newLength argument is less than the current length of the string builder, the string builder is truncated to contain exactly the number of characters given by the newLength argument. - * If the newLength argument is greater than or equal to the current length, sufficient null characters ('u0000') are appended to the string builder so that length becomes the newLength argument. - * The newLength argument must be greater than or equal to 0. - */ + /// Sets the length of this string builder. This string builder is altered to represent a new character sequence whose length is specified by the argument. For every nonnegative index + /// less than newLength, the character at index + /// in the new character sequence is the same as the character at index + /// in the old sequence if + /// is less than the length of the old character sequence; otherwise, it is the null character '\u0000'. In other words, if the newLength argument is less than the current length of the string builder, the string builder is truncated to contain exactly the number of characters given by the newLength argument. + /// If the newLength argument is greater than or equal to the current length, sufficient null characters ('u0000') are appended to the string builder so that length becomes the newLength argument. + /// The newLength argument must be greater than or equal to 0. public void setLength(int newLength){ return; //TODO codavaj!! } - /** - * Converts to a string representing the data in this string builder. A new String object is allocated and initialized to contain the character sequence currently represented by this string builder. This String is then returned. Subsequent changes to the string builder do not affect the contents of the String. - * Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string builder. Any subsequent operation that alters the content or capacity of the string builder must then make a copy of the internal builder at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation when it is implemented using a string builder. - */ + /// Converts to a string representing the data in this string builder. A new String object is allocated and initialized to contain the character sequence currently represented by this string builder. This String is then returned. Subsequent changes to the string builder do not affect the contents of the String. + /// Implementation advice: This method can be coded so as to create a new String object without allocating new memory to hold a copy of the character sequence. Instead, the string can share the memory used by the string builder. Any subsequent operation that alters the content or capacity of the string builder must then make a copy of the internal builder at that time. This strategy is effective for reducing the amount of memory allocated by a string concatenation operation when it is implemented using a string builder. public java.lang.String toString(){ return null; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/StringIndexOutOfBoundsException.java b/Ports/CLDC11/src/java/lang/StringIndexOutOfBoundsException.java index f328e3ba35..b7c1ca1acb 100644 --- a/Ports/CLDC11/src/java/lang/StringIndexOutOfBoundsException.java +++ b/Ports/CLDC11/src/java/lang/StringIndexOutOfBoundsException.java @@ -22,31 +22,23 @@ * have any questions. */ package java.lang; -/** - * Thrown by the charAt method in class String and by other String methods to indicate that an index is either negative or greater than or equal to the size of the string. - * Since: JDK1.0, CLDC 1.0 See Also:String.charAt(int) - */ +/// Thrown by the charAt method in class String and by other String methods to indicate that an index is either negative or greater than or equal to the size of the string. +/// Since: JDK1.0, CLDC 1.0 See Also:String.charAt(int) public class StringIndexOutOfBoundsException extends java.lang.IndexOutOfBoundsException{ - /** - * Constructs a StringIndexOutOfBoundsException with no detail message. - * JDK1.0. - */ + /// Constructs a StringIndexOutOfBoundsException with no detail message. + /// JDK1.0. public StringIndexOutOfBoundsException(){ //TODO codavaj!! } - /** - * Constructs a new StringIndexOutOfBoundsException class with an argument indicating the illegal index. - * index - the illegal index. - */ + /// Constructs a new StringIndexOutOfBoundsException class with an argument indicating the illegal index. + /// index - the illegal index. public StringIndexOutOfBoundsException(int index){ //TODO codavaj!! } - /** - * Constructs a StringIndexOutOfBoundsException with the specified detail message. - * s - the detail message. - */ + /// Constructs a StringIndexOutOfBoundsException with the specified detail message. + /// s - the detail message. public StringIndexOutOfBoundsException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/SuppressWarnings.java b/Ports/CLDC11/src/java/lang/SuppressWarnings.java index b6e4c936d9..955613ff49 100644 --- a/Ports/CLDC11/src/java/lang/SuppressWarnings.java +++ b/Ports/CLDC11/src/java/lang/SuppressWarnings.java @@ -21,14 +21,12 @@ import java.lang.annotation.Target; import java.lang.annotation.ElementType; -/** - *

- * An annotation that indicates a compiler should suppress any warnings of the - * type specified in the {@link #value()}. - *

- * - * @since 1.5 - */ +/// An annotation that indicates a compiler should suppress any warnings of the +/// type specified in the `#value()`. +/// +/// #### Since +/// +/// 1.5 @Target( { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.CONSTRUCTOR, ElementType.LOCAL_VARIABLE }) diff --git a/Ports/CLDC11/src/java/lang/System.java b/Ports/CLDC11/src/java/lang/System.java index 44a518c553..77c136b34f 100644 --- a/Ports/CLDC11/src/java/lang/System.java +++ b/Ports/CLDC11/src/java/lang/System.java @@ -22,76 +22,58 @@ * have any questions. */ package java.lang; -/** - * The System class contains several useful class fields and methods. It cannot be instantiated. - * Since: JDK1.0, CLDC 1.0 - */ +/// The System class contains several useful class fields and methods. It cannot be instantiated. +/// Since: JDK1.0, CLDC 1.0 public final class System{ - /** - * The "standard" error output stream. This stream is already open and ready to accept output data. - * Typically this stream corresponds to display output or another output destination specified by the host environment or user. By convention, this output stream is used to display error messages or other information that should come to the immediate attention of a user even if the principal output stream, the value of the variable out, has been redirected to a file or other destination that is typically not continuously monitored. - */ + /// The "standard" error output stream. This stream is already open and ready to accept output data. + /// Typically this stream corresponds to display output or another output destination specified by the host environment or user. By convention, this output stream is used to display error messages or other information that should come to the immediate attention of a user even if the principal output stream, the value of the variable out, has been redirected to a file or other destination that is typically not continuously monitored. public static final java.io.PrintStream err=null; - /** - * The "standard" output stream. This stream is already open and ready to accept output data. Typically this stream corresponds to display output or another output destination specified by the host environment or user. - * For simple stand-alone Java applications, a typical way to write a line of output data is: - * System.out.println(data) - * See the println methods in class PrintStream. - * See Also:PrintStream.println(), PrintStream.println(boolean), PrintStream.println(char), PrintStream.println(char[]), PrintStream.println(int), PrintStream.println(long), PrintStream.println(java.lang.Object), PrintStream.println(java.lang.String) - */ + /// The "standard" output stream. This stream is already open and ready to accept output data. Typically this stream corresponds to display output or another output destination specified by the host environment or user. + /// For simple stand-alone Java applications, a typical way to write a line of output data is: + /// System.out.println(data) + /// See the println methods in class PrintStream. + /// See Also:PrintStream.println(), PrintStream.println(boolean), PrintStream.println(char), PrintStream.println(char[]), PrintStream.println(int), PrintStream.println(long), PrintStream.println(java.lang.Object), PrintStream.println(java.lang.String) public static final java.io.PrintStream out=null; - /** - * Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array. A subsequence of array components are copied from the source array referenced by src to the destination array referenced by dst. The number of components copied is equal to the length argument. The components at positions srcOffset through srcOffset+length-1 in the source array are copied into positions dstOffset through dstOffset+length-1, respectively, of the destination array. - * If the src and dst arguments refer to the same array object, then the copying is performed as if the components at positions srcOffset through srcOffset+length-1 were first copied to a temporary array with length components and then the contents of the temporary array were copied into positions dstOffset through dstOffset+length-1 of the destination array. - * If dst is null, then a NullPointerException is thrown. - * If src is null, then a NullPointerException is thrown and the destination array is not modified. - * Otherwise, if any of the following is true, an ArrayStoreException is thrown and the destination is not modified: The src argument refers to an object that is not an array. The dst argument refers to an object that is not an array. The src argument and dst argument refer to arrays whose component types are different primitive types. The src argument refers to an array with a primitive component type and the dst argument refers to an array with a reference component type. The src argument refers to an array with a reference component type and the dst argument refers to an array with a primitive component type. - * Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified: The srcOffset argument is negative. The dstOffset argument is negative. The length argument is negative. srcOffset+length is greater than src.length, the length of the source array. dstOffset+length is greater than dst.length, the length of the destination array. - * Otherwise, if any actual component of the source array from position srcOffset through srcOffset+length-1 cannot be converted to the component type of the destination array by assignment conversion, an ArrayStoreException is thrown. In this case, let k be the smallest nonnegative integer less than length such that src[srcOffset+k] cannot be converted to the component type of the destination array; when the exception is thrown, source array components from positions srcOffset through srcOffset+k-1 will already have been copied to destination array positions dstOffset through dstOffset+k-1 and no other positions of the destination array will have been modified. (Because of the restrictions already itemized, this paragraph effectively applies only to the situation where both arrays have component types that are reference types.) - */ + /// Copies an array from the specified source array, beginning at the specified position, to the specified position of the destination array. A subsequence of array components are copied from the source array referenced by src to the destination array referenced by dst. The number of components copied is equal to the length argument. The components at positions srcOffset through srcOffset+length-1 in the source array are copied into positions dstOffset through dstOffset+length-1, respectively, of the destination array. + /// If the src and dst arguments refer to the same array object, then the copying is performed as if the components at positions srcOffset through srcOffset+length-1 were first copied to a temporary array with length components and then the contents of the temporary array were copied into positions dstOffset through dstOffset+length-1 of the destination array. + /// If dst is null, then a NullPointerException is thrown. + /// If src is null, then a NullPointerException is thrown and the destination array is not modified. + /// Otherwise, if any of the following is true, an ArrayStoreException is thrown and the destination is not modified: The src argument refers to an object that is not an array. The dst argument refers to an object that is not an array. The src argument and dst argument refer to arrays whose component types are different primitive types. The src argument refers to an array with a primitive component type and the dst argument refers to an array with a reference component type. The src argument refers to an array with a reference component type and the dst argument refers to an array with a primitive component type. + /// Otherwise, if any of the following is true, an IndexOutOfBoundsException is thrown and the destination is not modified: The srcOffset argument is negative. The dstOffset argument is negative. The length argument is negative. srcOffset+length is greater than src.length, the length of the source array. dstOffset+length is greater than dst.length, the length of the destination array. + /// Otherwise, if any actual component of the source array from position srcOffset through srcOffset+length-1 cannot be converted to the component type of the destination array by assignment conversion, an ArrayStoreException is thrown. In this case, let k be the smallest nonnegative integer less than length such that src[srcOffset+k] cannot be converted to the component type of the destination array; when the exception is thrown, source array components from positions srcOffset through srcOffset+k-1 will already have been copied to destination array positions dstOffset through dstOffset+k-1 and no other positions of the destination array will have been modified. (Because of the restrictions already itemized, this paragraph effectively applies only to the situation where both arrays have component types that are reference types.) public static void arraycopy(java.lang.Object src, int srcOffset, java.lang.Object dst, int dstOffset, int length){ return; //TODO codavaj!! } - /** - * Returns the current time in milliseconds. - */ + /// Returns the current time in milliseconds. public static long currentTimeMillis(){ return 0l; //TODO codavaj!! } - /** - * Terminates the currently running Java application. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination. - * This method calls the exit method in class Runtime. This method never returns normally. - * The call System.exit(n) is effectively equivalent to the call: - * Runtime.getRuntime().exit(n) - */ + /// Terminates the currently running Java application. The argument serves as a status code; by convention, a nonzero status code indicates abnormal termination. + /// This method calls the exit method in class Runtime. This method never returns normally. + /// The call System.exit(n) is effectively equivalent to the call: + /// Runtime.getRuntime().exit(n) public static void exit(int status){ return; //TODO codavaj!! } - /** - * Runs the garbage collector. - * Calling the gc method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to reclaim space from all discarded objects. - * The call System.gc() is effectively equivalent to the call: - * Runtime.getRuntime().gc() - */ + /// Runs the garbage collector. + /// Calling the gc method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to reclaim space from all discarded objects. + /// The call System.gc() is effectively equivalent to the call: + /// Runtime.getRuntime().gc() public static void gc(){ return; //TODO codavaj!! } - /** - * Gets the system property indicated by the specified key. - */ + /// Gets the system property indicated by the specified key. public static java.lang.String getProperty(java.lang.String key){ return null; //TODO codavaj!! } - /** - * Returns the same hashcode for the given object as would be returned by the default method hashCode(), whether or not the given object's class overrides hashCode(). The hashcode for the null reference is zero. - */ + /// Returns the same hashcode for the given object as would be returned by the default method hashCode(), whether or not the given object's class overrides hashCode(). The hashcode for the null reference is zero. public static int identityHashCode(java.lang.Object x){ return 0; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Thread.java b/Ports/CLDC11/src/java/lang/Thread.java index add8b473ba..c949dfa9a5 100644 --- a/Ports/CLDC11/src/java/lang/Thread.java +++ b/Ports/CLDC11/src/java/lang/Thread.java @@ -22,149 +22,107 @@ * have any questions. */ package java.lang; -/** - * A thread is a thread of execution in a program. The Java Virtual Machine allows an application to have multiple threads of execution running concurrently. - */ +/// A thread is a thread of execution in a program. The Java Virtual Machine allows an application to have multiple threads of execution running concurrently. public class Thread implements java.lang.Runnable{ - /** - * The maximum priority that a thread can have. - * See Also:Constant Field Values - */ + /// The maximum priority that a thread can have. + /// See Also:Constant Field Values public static final int MAX_PRIORITY=10; - /** - * The minimum priority that a thread can have. - * See Also:Constant Field Values - */ + /// The minimum priority that a thread can have. + /// See Also:Constant Field Values public static final int MIN_PRIORITY=1; - /** - * The default priority that is assigned to a thread. - * See Also:Constant Field Values - */ + /// The default priority that is assigned to a thread. + /// See Also:Constant Field Values public static final int NORM_PRIORITY=5; - /** - * Allocates a new Thread object. - * Threads created this way must have overridden their run() method to actually do anything. - */ + /// Allocates a new Thread object. + /// Threads created this way must have overridden their run() method to actually do anything. public Thread(){ //TODO codavaj!! } - /** - * Allocates a new Thread object with a specific target object whose run method is called. - * target - the object whose run method is called. - */ + /// Allocates a new Thread object with a specific target object whose run method is called. + /// target - the object whose run method is called. public Thread(java.lang.Runnable target){ //TODO codavaj!! } - /** - * Allocates a new Thread object with the given target and name. - * target - the object whose run method is called.name - the name of the new thread. - */ + /// Allocates a new Thread object with the given target and name. + /// target - the object whose run method is called.name - the name of the new thread. public Thread(java.lang.Runnable target, java.lang.String name){ //TODO codavaj!! } - /** - * Allocates a new Thread object with the given name. Threads created this way must have overridden their run() method to actually do anything. - * name - the name of the new thread. - */ + /// Allocates a new Thread object with the given name. Threads created this way must have overridden their run() method to actually do anything. + /// name - the name of the new thread. public Thread(java.lang.String name){ //TODO codavaj!! } - /** - * Returns the current number of active threads in the virtual machine. - */ + /// Returns the current number of active threads in the virtual machine. public static int activeCount(){ return 0; //TODO codavaj!! } - /** - * Returns a reference to the currently executing Thread object. - */ + /// Returns a reference to the currently executing Thread object. public static java.lang.Thread currentThread(){ return null; //TODO codavaj!! } - /** - * Returns this thread's name. Note that in CLDC the name of the thread can only be set when creating the thread. - */ + /// Returns this thread's name. Note that in CLDC the name of the thread can only be set when creating the thread. public final java.lang.String getName(){ return null; //TODO codavaj!! } - /** - * Returns this thread's priority. - */ + /// Returns this thread's priority. public final int getPriority(){ return 0; //TODO codavaj!! } - /** - * Interrupts this thread. In an implementation conforming to the CLDC Specification, this operation is not required to cancel or clean up any pending I/O operations that the thread may be waiting for. - */ + /// Interrupts this thread. In an implementation conforming to the CLDC Specification, this operation is not required to cancel or clean up any pending I/O operations that the thread may be waiting for. public void interrupt(){ return; //TODO codavaj!! } - /** - * Tests if this thread is alive. A thread is alive if it has been started and has not yet died. - */ + /// Tests if this thread is alive. A thread is alive if it has been started and has not yet died. public final boolean isAlive(){ return false; //TODO codavaj!! } - /** - * Waits for this thread to die. - */ + /// Waits for this thread to die. public final void join() throws java.lang.InterruptedException{ return; //TODO codavaj!! } - /** - * If this thread was constructed using a separate Runnable run object, then that Runnable object's run method is called; otherwise, this method does nothing and returns. - * Subclasses of Thread should override this method. - */ + /// If this thread was constructed using a separate Runnable run object, then that Runnable object's run method is called; otherwise, this method does nothing and returns. + /// Subclasses of Thread should override this method. public void run(){ return; //TODO codavaj!! } - /** - * Changes the priority of this thread. - */ + /// Changes the priority of this thread. public final void setPriority(int newPriority){ return; //TODO codavaj!! } - /** - * Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. The thread does not lose ownership of any monitors. - */ + /// Causes the currently executing thread to sleep (temporarily cease execution) for the specified number of milliseconds. The thread does not lose ownership of any monitors. public static void sleep(long millis) throws java.lang.InterruptedException{ return; //TODO codavaj!! } - /** - * Causes this thread to begin execution; the Java Virtual Machine calls the run method of this thread. - * The result is that two threads are running concurrently: the current thread (which returns from the call to the start method) and the other thread (which executes its run method). - */ + /// Causes this thread to begin execution; the Java Virtual Machine calls the run method of this thread. + /// The result is that two threads are running concurrently: the current thread (which returns from the call to the start method) and the other thread (which executes its run method). public void start(){ return; //TODO codavaj!! } - /** - * Returns a string representation of this thread, including the thread's name and priority. - */ + /// Returns a string representation of this thread, including the thread's name and priority. public java.lang.String toString(){ return null; //TODO codavaj!! } - /** - * Causes the currently executing thread object to temporarily pause and allow other threads to execute. - */ + /// Causes the currently executing thread object to temporarily pause and allow other threads to execute. public static void yield(){ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/ThreadLocal.java b/Ports/CLDC11/src/java/lang/ThreadLocal.java index a73757c3c4..080bffe17f 100644 --- a/Ports/CLDC11/src/java/lang/ThreadLocal.java +++ b/Ports/CLDC11/src/java/lang/ThreadLocal.java @@ -10,10 +10,7 @@ import java.util.Map; import java.util.Set; -/** - * - * @author shannah - */ +/// @author shannah public class ThreadLocal extends Object { private Map value = new HashMap(); diff --git a/Ports/CLDC11/src/java/lang/Throwable.java b/Ports/CLDC11/src/java/lang/Throwable.java index 4d6f8afb30..a45188ab72 100644 --- a/Ports/CLDC11/src/java/lang/Throwable.java +++ b/Ports/CLDC11/src/java/lang/Throwable.java @@ -22,85 +22,73 @@ * have any questions. */ package java.lang; -/** - * The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or of one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause. - * Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data). - * By convention, class Throwable and its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce an error message. - * A Throwable class contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error. - * Here is one example of catching an exception: - * Since: JDK1.0, CLDC 1.0 - */ +/// The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or of one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause. +/// Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data). +/// By convention, class Throwable and its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce an error message. +/// A Throwable class contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error. +/// Here is one example of catching an exception: +/// Since: JDK1.0, CLDC 1.0 public class Throwable{ - /** - * Constructs a new Throwable with null as its error message string. - */ + /// Constructs a new Throwable with null as its error message string. public Throwable(){ //TODO codavaj!! } - /** - * Constructs a new throwable with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause). - * @param cause The cause - */ + /// Constructs a new throwable with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause). + /// + /// #### Parameters + /// + /// - `cause`: The cause public Throwable(Throwable cause) { } - /** - * @deprecated DO NOT USE THIS METHOD, its here just to get the compiler working and isn't intended for use - */ + /// #### Deprecated + /// + /// DO NOT USE THIS METHOD, its here just to get the compiler working and isn't intended for use public Throwable initCause(Throwable cause) { return null; } - /** - * Returns the cause of this throwable or null if the cause is nonexistent or unknown. - * @return - */ + /// Returns the cause of this throwable or null if the cause is nonexistent or unknown. public Throwable getCause() { return null; } - /** - * Constructs a new Throwable with the specified error message. - * message - the error message. The error message is saved for later retrieval by the - * method. - */ + /// Constructs a new Throwable with the specified error message. + /// message - the error message. The error message is saved for later retrieval by the + /// method. public Throwable(java.lang.String message){ //TODO codavaj!! } - /** - * Constructs a new throwable with the specified detail message and cause. - * @param message The error message. - * @param cause The cause - */ + /// Constructs a new throwable with the specified detail message and cause. + /// + /// #### Parameters + /// + /// - `message`: The error message. + /// + /// - `cause`: The cause public Throwable(java.lang.String message, Throwable cause) { } - /** - * Returns the error message string of this Throwable object. - */ + /// Returns the error message string of this Throwable object. public java.lang.String getMessage(){ return null; //TODO codavaj!! } - /** - * Prints this Throwable and its backtrace to the standard error stream. This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the - * method for this object. - * The format of the backtrace information depends on the implementation. - */ + /// Prints this Throwable and its backtrace to the standard error stream. This method prints a stack trace for this Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the + /// method for this object. + /// The format of the backtrace information depends on the implementation. public void printStackTrace(){ return; //TODO codavaj!! } - /** - * Returns a short description of this Throwable object. If this Throwable object was - * with an error message string, then the result is the concatenation of three strings: The name of the actual class of this object ": " (a colon and a space) The result of the - * method for this object If this Throwable object was - * with no error message string, then the name of the actual class of this object is returned. - */ + /// Returns a short description of this Throwable object. If this Throwable object was + /// with an error message string, then the result is the concatenation of three strings: The name of the actual class of this object ": " (a colon and a space) The result of the + /// method for this object If this Throwable object was + /// with no error message string, then the name of the actual class of this object is returned. public java.lang.String toString(){ return null; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/UnsupportedOperationException.java b/Ports/CLDC11/src/java/lang/UnsupportedOperationException.java index 2af138a954..ef93993425 100644 --- a/Ports/CLDC11/src/java/lang/UnsupportedOperationException.java +++ b/Ports/CLDC11/src/java/lang/UnsupportedOperationException.java @@ -23,10 +23,7 @@ package java.lang; -/** - * - * @author Shai Almog - */ +/// @author Shai Almog public class UnsupportedOperationException extends RuntimeException { public UnsupportedOperationException() { } diff --git a/Ports/CLDC11/src/java/lang/VirtualMachineError.java b/Ports/CLDC11/src/java/lang/VirtualMachineError.java index 46eb9a617c..0c5e7f7317 100644 --- a/Ports/CLDC11/src/java/lang/VirtualMachineError.java +++ b/Ports/CLDC11/src/java/lang/VirtualMachineError.java @@ -22,22 +22,16 @@ * have any questions. */ package java.lang; -/** - * Thrown to indicate that the Java Virtual Machine is broken or has run out of resources necessary for it to continue operating. - * Since: JDK1.0, CLDC 1.0 - */ +/// Thrown to indicate that the Java Virtual Machine is broken or has run out of resources necessary for it to continue operating. +/// Since: JDK1.0, CLDC 1.0 public abstract class VirtualMachineError extends java.lang.Error{ - /** - * Constructs a VirtualMachineError with no detail message. - */ + /// Constructs a VirtualMachineError with no detail message. public VirtualMachineError(){ //TODO codavaj!! } - /** - * Constructs a VirtualMachineError with the specified detail message. - * s - the detail message. - */ + /// Constructs a VirtualMachineError with the specified detail message. + /// s - the detail message. public VirtualMachineError(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/Void.java b/Ports/CLDC11/src/java/lang/Void.java index 7c84100e41..57954bd36d 100644 --- a/Ports/CLDC11/src/java/lang/Void.java +++ b/Ports/CLDC11/src/java/lang/Void.java @@ -23,10 +23,7 @@ */ package java.lang; -/** - * - * @author Shai Almog - */ +/// @author Shai Almog public final class Void { public static final Class TYPE = Void.class; } diff --git a/Ports/CLDC11/src/java/lang/annotation/Annotation.java b/Ports/CLDC11/src/java/lang/annotation/Annotation.java index a23ce298a1..3f70a2af1c 100644 --- a/Ports/CLDC11/src/java/lang/annotation/Annotation.java +++ b/Ports/CLDC11/src/java/lang/annotation/Annotation.java @@ -1,54 +1,44 @@ -/* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores - * CA 94065 USA or visit www.oracle.com if you need additional information or - * have any questions. - */ -package java.lang.annotation; - -/** - * A mirror of java.lang.Annotation. - * - * @author Toby Reyelts - */ -public interface Annotation { - - /** - * Returns the annotation type of this annotation. - */ - Class annotationType(); - - /** - * Returns true if the specified object represents an annotation that is - * logically equivalent to this one. - */ - boolean equals(Object obj); - - /** - * Returns the hash code of this annotation, as defined below: - */ - int hashCode(); - - /** - * Returns a string representation of this annotation. - */ - String toString(); - -} +/* + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores + * CA 94065 USA or visit www.oracle.com if you need additional information or + * have any questions. + */ +package java.lang.annotation; + +/// A mirror of java.lang.Annotation. +/// +/// @author Toby Reyelts +public interface Annotation { + + /// Returns the annotation type of this annotation. + Class annotationType(); + + /// Returns true if the specified object represents an annotation that is + /// logically equivalent to this one. + boolean equals(Object obj); + + /// Returns the hash code of this annotation, as defined below: + int hashCode(); + + /// Returns a string representation of this annotation. + String toString(); + +} diff --git a/Ports/CLDC11/src/java/lang/annotation/AnnotationFormatError.java b/Ports/CLDC11/src/java/lang/annotation/AnnotationFormatError.java index 9f58051b0b..8a81e1fd86 100644 --- a/Ports/CLDC11/src/java/lang/annotation/AnnotationFormatError.java +++ b/Ports/CLDC11/src/java/lang/annotation/AnnotationFormatError.java @@ -1,44 +1,42 @@ -/* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores - * CA 94065 USA or visit www.oracle.com if you need additional information or - * have any questions. - */ -package java.lang.annotation; - -/** - * A mirror of java.lang.annotation.AnnotationFormatError. - * - * @author Toby Reyelts - */ -public class AnnotationFormatError extends Error { - - public AnnotationFormatError(final String message) { - super(message); - } - - public AnnotationFormatError(final String message, final Throwable cause) { - super(message); - } - - public AnnotationFormatError(final Throwable cause) { - super(cause.toString()); - } -} +/* + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores + * CA 94065 USA or visit www.oracle.com if you need additional information or + * have any questions. + */ +package java.lang.annotation; + +/// A mirror of java.lang.annotation.AnnotationFormatError. +/// +/// @author Toby Reyelts +public class AnnotationFormatError extends Error { + + public AnnotationFormatError(final String message) { + super(message); + } + + public AnnotationFormatError(final String message, final Throwable cause) { + super(message); + } + + public AnnotationFormatError(final Throwable cause) { + super(cause.toString()); + } +} diff --git a/Ports/CLDC11/src/java/lang/annotation/ElementType.java b/Ports/CLDC11/src/java/lang/annotation/ElementType.java index a0d0c2f339..6af067e3be 100644 --- a/Ports/CLDC11/src/java/lang/annotation/ElementType.java +++ b/Ports/CLDC11/src/java/lang/annotation/ElementType.java @@ -1,43 +1,40 @@ -/* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores - * CA 94065 USA or visit www.oracle.com if you need additional information or - * have any questions. - */ - -package java.lang.annotation; - -/** - * A mirror of java.lang.annotation.ElementType. - * - * @author Toby Reyelts - * - */ -public enum ElementType { - ANNOTATION_TYPE, - CONSTRUCTOR, - FIELD, - LOCAL_VARIABLE, - METHOD, - PACKAGE, - PARAMETER, - TYPE; -} - +/* + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores + * CA 94065 USA or visit www.oracle.com if you need additional information or + * have any questions. + */ + +package java.lang.annotation; + +/// A mirror of java.lang.annotation.ElementType. +/// +/// @author Toby Reyelts +public enum ElementType { + ANNOTATION_TYPE, + CONSTRUCTOR, + FIELD, + LOCAL_VARIABLE, + METHOD, + PACKAGE, + PARAMETER, + TYPE; +} + diff --git a/Ports/CLDC11/src/java/lang/annotation/IncompleteAnnotationException.java b/Ports/CLDC11/src/java/lang/annotation/IncompleteAnnotationException.java index 1f390e4206..3fb90bc9c2 100644 --- a/Ports/CLDC11/src/java/lang/annotation/IncompleteAnnotationException.java +++ b/Ports/CLDC11/src/java/lang/annotation/IncompleteAnnotationException.java @@ -1,53 +1,51 @@ -/* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores - * CA 94065 USA or visit www.oracle.com if you need additional information or - * have any questions. - */ -package java.lang.annotation; - -import java.lang.annotation.Annotation; - -/** - * A mirror of java.lang.annotation.IncompleteAnnotationException. - * - * @author Toby Reyelts - */ -public class IncompleteAnnotationException extends RuntimeException { - - private final Class annotationType_; - - private final String elementName_; - - public IncompleteAnnotationException(final Class annotationType, final String elementName) { - super(elementName + " in " + annotationType); - this.annotationType_ = annotationType; - this.elementName_ = elementName; - } - - public Class annotationType() { - return annotationType_; - } - - public String elementName() { - return elementName_; - } - -} +/* + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores + * CA 94065 USA or visit www.oracle.com if you need additional information or + * have any questions. + */ +package java.lang.annotation; + +import java.lang.annotation.Annotation; + +/// A mirror of java.lang.annotation.IncompleteAnnotationException. +/// +/// @author Toby Reyelts +public class IncompleteAnnotationException extends RuntimeException { + + private final Class annotationType_; + + private final String elementName_; + + public IncompleteAnnotationException(final Class annotationType, final String elementName) { + super(elementName + " in " + annotationType); + this.annotationType_ = annotationType; + this.elementName_ = elementName; + } + + public Class annotationType() { + return annotationType_; + } + + public String elementName() { + return elementName_; + } + +} diff --git a/Ports/CLDC11/src/java/lang/annotation/RetentionPolicy.java b/Ports/CLDC11/src/java/lang/annotation/RetentionPolicy.java index 9c8bd89ecf..5a4597e465 100644 --- a/Ports/CLDC11/src/java/lang/annotation/RetentionPolicy.java +++ b/Ports/CLDC11/src/java/lang/annotation/RetentionPolicy.java @@ -1,38 +1,35 @@ -/* - * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores - * CA 94065 USA or visit www.oracle.com if you need additional information or - * have any questions. - */ - -package java.lang.annotation; - -/** - * A mirror of java.lang.annotation.RetentionPolicy. - * - * @author Toby Reyelts - * - */ -public enum RetentionPolicy { - CLASS, - RUNTIME, - SOURCE; -} - +/* + * Copyright (c) 2008, 2010, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores + * CA 94065 USA or visit www.oracle.com if you need additional information or + * have any questions. + */ + +package java.lang.annotation; + +/// A mirror of java.lang.annotation.RetentionPolicy. +/// +/// @author Toby Reyelts +public enum RetentionPolicy { + CLASS, + RUNTIME, + SOURCE; +} + diff --git a/Ports/CLDC11/src/java/lang/invoke/CallSite.java b/Ports/CLDC11/src/java/lang/invoke/CallSite.java index 991cbd741e..1c592da116 100644 --- a/Ports/CLDC11/src/java/lang/invoke/CallSite.java +++ b/Ports/CLDC11/src/java/lang/invoke/CallSite.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated these classes are used internally for Lambda compatibility - */ +/// #### Deprecated +/// +/// these classes are used internally for Lambda compatibility public abstract class CallSite { public CallSite() {} diff --git a/Ports/CLDC11/src/java/lang/invoke/LambdaMetafactory.java b/Ports/CLDC11/src/java/lang/invoke/LambdaMetafactory.java index a7514ad5c8..373c954b2f 100644 --- a/Ports/CLDC11/src/java/lang/invoke/LambdaMetafactory.java +++ b/Ports/CLDC11/src/java/lang/invoke/LambdaMetafactory.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated these classes are used internally for Lambda compatibility - */ +/// #### Deprecated +/// +/// these classes are used internally for Lambda compatibility public class LambdaMetafactory { public static final int FLAG_SERIALIZABLE = 1; public static final int FLAG_MARKERS = 2; diff --git a/Ports/CLDC11/src/java/lang/invoke/MethodHandle.java b/Ports/CLDC11/src/java/lang/invoke/MethodHandle.java index ae77c308a4..1f494303c3 100644 --- a/Ports/CLDC11/src/java/lang/invoke/MethodHandle.java +++ b/Ports/CLDC11/src/java/lang/invoke/MethodHandle.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated these classes are used internally for Lambda compatibility - */ +/// #### Deprecated +/// +/// these classes are used internally for Lambda compatibility public abstract class MethodHandle { public MethodHandle() { } diff --git a/Ports/CLDC11/src/java/lang/invoke/MethodHandles.java b/Ports/CLDC11/src/java/lang/invoke/MethodHandles.java index 6a4df29d96..6d7825b0ec 100644 --- a/Ports/CLDC11/src/java/lang/invoke/MethodHandles.java +++ b/Ports/CLDC11/src/java/lang/invoke/MethodHandles.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated these classes are used internally for Lambda compatibility - */ +/// #### Deprecated +/// +/// these classes are used internally for Lambda compatibility public abstract class MethodHandles { public MethodHandles() { } diff --git a/Ports/CLDC11/src/java/lang/invoke/MethodType.java b/Ports/CLDC11/src/java/lang/invoke/MethodType.java index 88b8a1dd67..65d123a411 100644 --- a/Ports/CLDC11/src/java/lang/invoke/MethodType.java +++ b/Ports/CLDC11/src/java/lang/invoke/MethodType.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated these classes are used internally for Lambda compatibility - */ +/// #### Deprecated +/// +/// these classes are used internally for Lambda compatibility public class MethodType { public MethodType() {} public static java.lang.invoke.MethodType methodType(java.lang.Class a, java.lang.Class[] b) { diff --git a/Ports/CLDC11/src/java/lang/invoke/StringConcatFactory.java b/Ports/CLDC11/src/java/lang/invoke/StringConcatFactory.java index 140c598ced..a419be93ee 100644 --- a/Ports/CLDC11/src/java/lang/invoke/StringConcatFactory.java +++ b/Ports/CLDC11/src/java/lang/invoke/StringConcatFactory.java @@ -23,9 +23,9 @@ */ package java.lang.invoke; -/** - * @deprecated this class is used internally for String concatenation compatibility - */ +/// #### Deprecated +/// +/// this class is used internally for String concatenation compatibility public final class StringConcatFactory { private StringConcatFactory() { } diff --git a/Ports/CLDC11/src/java/lang/ref/Reference.java b/Ports/CLDC11/src/java/lang/ref/Reference.java index bdec7adebd..a121b02e01 100644 --- a/Ports/CLDC11/src/java/lang/ref/Reference.java +++ b/Ports/CLDC11/src/java/lang/ref/Reference.java @@ -22,21 +22,15 @@ * have any questions. */ package java.lang.ref; -/** - * Abstract base class for reference objects. This class defines the operations common to all reference objects. Because reference objects are implemented in close cooperation with the garbage collector, this class may not be subclassed directly. - * Since: JDK1.2, CLDC 1.1 - */ +/// Abstract base class for reference objects. This class defines the operations common to all reference objects. Because reference objects are implemented in close cooperation with the garbage collector, this class may not be subclassed directly. +/// Since: JDK1.2, CLDC 1.1 public abstract class Reference{ - /** - * Clears this reference object. - */ + /// Clears this reference object. public void clear(){ return; //TODO codavaj!! } - /** - * Returns this reference object's referent. If this reference object has been cleared, either by the program or by the garbage collector, then this method returns null. - */ + /// Returns this reference object's referent. If this reference object has been cleared, either by the program or by the garbage collector, then this method returns null. public java.lang.Object get(){ return null; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/ref/WeakReference.java b/Ports/CLDC11/src/java/lang/ref/WeakReference.java index ae8de81250..bbf3209485 100644 --- a/Ports/CLDC11/src/java/lang/ref/WeakReference.java +++ b/Ports/CLDC11/src/java/lang/ref/WeakReference.java @@ -22,14 +22,10 @@ * have any questions. */ package java.lang.ref; -/** - * This class provides support for weak references. Weak references are most often used to implement canonicalizing mappings. Suppose that the garbage collector determines at a certain point in time that an object is weakly reachable. At that time it will atomically clear all the weak references to that object and all weak references to any other weakly- reachable objects from which that object is reachable through a chain of strong and weak references. - * Since: JDK1.2, CLDC 1.1 - */ +/// This class provides support for weak references. Weak references are most often used to implement canonicalizing mappings. Suppose that the garbage collector determines at a certain point in time that an object is weakly reachable. At that time it will atomically clear all the weak references to that object and all weak references to any other weakly- reachable objects from which that object is reachable through a chain of strong and weak references. +/// Since: JDK1.2, CLDC 1.1 public class WeakReference extends java.lang.ref.Reference{ - /** - * Creates a new weak reference that refers to the given object. - */ + /// Creates a new weak reference that refers to the given object. public WeakReference(java.lang.Object ref){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/lang/reflect/Array.java b/Ports/CLDC11/src/java/lang/reflect/Array.java index 268a5d8171..cc0397f7eb 100644 --- a/Ports/CLDC11/src/java/lang/reflect/Array.java +++ b/Ports/CLDC11/src/java/lang/reflect/Array.java @@ -22,10 +22,8 @@ */ package java.lang.reflect; -/** - * Added this for Kotlin - * @author shannah - */ +/// Added this for Kotlin +/// @author shannah public class Array { public static Object newInstance(Class componentType, int[] dimensions) { diff --git a/Ports/CLDC11/src/java/lang/reflect/Constructor.java b/Ports/CLDC11/src/java/lang/reflect/Constructor.java index 853881aa2c..cdee6e8ee0 100644 --- a/Ports/CLDC11/src/java/lang/reflect/Constructor.java +++ b/Ports/CLDC11/src/java/lang/reflect/Constructor.java @@ -5,10 +5,7 @@ */ package java.lang.reflect; -/** - * - * @author shannah - */ +/// @author shannah public class Constructor { public String getName() { return null; diff --git a/Ports/CLDC11/src/java/lang/reflect/Method.java b/Ports/CLDC11/src/java/lang/reflect/Method.java index 2b957869e3..2bb485b6c4 100644 --- a/Ports/CLDC11/src/java/lang/reflect/Method.java +++ b/Ports/CLDC11/src/java/lang/reflect/Method.java @@ -5,10 +5,7 @@ */ package java.lang.reflect; -/** - * - * @author shannah - */ +/// @author shannah public class Method { public String getName() { return null; diff --git a/Ports/CLDC11/src/java/lang/reflect/Type.java b/Ports/CLDC11/src/java/lang/reflect/Type.java index a33939c8e2..1a15869cec 100644 --- a/Ports/CLDC11/src/java/lang/reflect/Type.java +++ b/Ports/CLDC11/src/java/lang/reflect/Type.java @@ -5,10 +5,7 @@ */ package java.lang.reflect; -/** - * - * @author shannah - */ +/// @author shannah public interface Type { } diff --git a/Ports/CLDC11/src/java/net/URI.java b/Ports/CLDC11/src/java/net/URI.java index ac1cf36220..1443180d27 100644 --- a/Ports/CLDC11/src/java/net/URI.java +++ b/Ports/CLDC11/src/java/net/URI.java @@ -26,158 +26,120 @@ import java.util.List; import java.util.StringTokenizer; -/** - * An implementation of a Univeral Resource Identifier (URI). While the output - * is mostly compatible with the Java 6 API, there are a few somewhat subtle - * differences: - * - * 
- * 1) For socket related URIs, the toString() methods use semicolon (;) as the
- *    query marker instead of the normal question mark (?), and the parameters are separated
- *    with a semicolon instead of the normal ampersand (&).  With this, the URIs are compatible
- *    with those used by J2ME socket connectors.  (The Java 6 API treats socket URIs as URNs).
- * 2) This implementation does not yet "rigorously parse IPv4" addresses like the Java 6 version does,
- *    the host address is simply stored as provided by the caller.  This will be enhanced using the
- *    InetAddress class when available.
- * 3) The characters defined as legal "other characters" are not all interpreted correctly, which
- *    just means some unicode characters will get encoded that aren't required to be.  The 
- *    method URIHelper.isLegalUnicode() needs to be inspected further.
- * 4) Because of 3) toASCIIString() and toString() return the same value.
- * TODO: finish this list
- *
- * - * @author Eric Coolman - * - * @see http://docs.oracle.com/javase/6/docs/api/java/net/URI.html - * @see http://en.wikipedia.org/wiki/Uniform_resource_identifier - * @see http://en.wikipedia.org/wiki/Uniform_resource_name - * @see http://www.ietf.org/rfc/rfc2396.txt - * @see http://www.ietf.org/rfc/rfc2732.txt - * @see http://tools.ietf.org/html/rfc2141 - */ +/// An implementation of a Univeral Resource Identifier (URI). While the output +/// is mostly compatible with the Java 6 API, there are a few somewhat subtle +/// differences: +/// +/// ```java +/// 1) For socket related URIs, the toString() methods use semicolon (;) as the +/// query marker instead of the normal question mark (?), and the parameters are separated +/// with a semicolon instead of the normal ampersand (&). With this, the URIs are compatible +/// with those used by J2ME socket connectors. (The Java 6 API treats socket URIs as URNs). +/// 2) This implementation does not yet "rigorously parse IPv4" addresses like the Java 6 version does, +/// the host address is simply stored as provided by the caller. This will be enhanced using the +/// InetAddress class when available. +/// 3) The characters defined as legal "other characters" are not all interpreted correctly, which +/// just means some unicode characters will get encoded that aren't required to be. The +/// method URIHelper.isLegalUnicode() needs to be inspected further. +/// 4) Because of 3) toASCIIString() and toString() return the same value. +/// TODO: finish this list +/// ``` +/// +/// @author Eric Coolman +/// +/// #### See also +/// +/// - [http://docs.oracle.com/javase/6/docs/api/java/net/URI.html](http://docs.oracle.com/javase/6/docs/api/java/net/URI.html) +/// +/// - [http://en.wikipedia.org/wiki/Uniform_resource_identifier](http://en.wikipedia.org/wiki/Uniform_resource_identifier) +/// +/// - [http://en.wikipedia.org/wiki/Uniform_resource_name](http://en.wikipedia.org/wiki/Uniform_resource_name) +/// +/// - [http://www.ietf.org/rfc/rfc2396.txt](http://www.ietf.org/rfc/rfc2396.txt) +/// +/// - [http://www.ietf.org/rfc/rfc2732.txt](http://www.ietf.org/rfc/rfc2732.txt) +/// +/// - [http://tools.ietf.org/html/rfc2141](http://tools.ietf.org/html/rfc2141) public class URI { - /** - * Characters that are valid within a URI - */ + /// Characters that are valid within a URI static final String UNRESERVED_EXTRAS = "_-!.~'()*"; - /** - * Characters that have special meaning within a URI. - */ + /// Characters that have special meaning within a URI. static final String PUNCTUATION = ",;:$&+="; - /** - * More characters that have special meaning within a URI. - */ + /// More characters that have special meaning within a URI. static final String RESERVED = PUNCTUATION + "?/[]@"; - /** - * Character that separates the scheme from the rest of the URI. - */ + /// Character that separates the scheme from the rest of the URI. static final char SCHEME_SEPARATOR = ':'; - /** - * Character that separates the port value within an authority. - */ + /// Character that separates the port value within an authority. static final char PORT_SEPARATOR = ':'; - /** - * Character that separates the user info value within an authority. - */ + /// Character that separates the user info value within an authority. static final char USERINFO_SEPARATOR = '@'; - /** - * Character that separates the path value from the authority - */ + /// Character that separates the path value from the authority static final char PATH_SEPARATOR = '/'; - /** - * A marker that identifies an authority value follows - */ + /// A marker that identifies an authority value follows static final String AUTHORITY_MARKER = "//"; - /** - * Character that identifies an escaped octet value. - */ + /// Character that identifies an escaped octet value. static final char QUOTE_MARKER = '%'; - /** - * Character that identifies the start of a query. - */ + /// Character that identifies the start of a query. static final char QUERY_MARKER = '?'; - /** - * Character that separates arguments within a query - */ + /// Character that separates arguments within a query static final char QUERY_SEPARATOR = '&'; - /** - * Character that separates name/value within a query parameter. - */ + /// Character that separates name/value within a query parameter. static final char PARAMETER_SEPARATOR = '='; - /** - * Character that separates arguments within a query for socket-based URLs. - */ + /// Character that separates arguments within a query for socket-based URLs. static final char SOCKET_QUERY_SEPARATOR = ';'; - /** - * Character that identifies the start of a fragment. - */ + /// Character that identifies the start of a fragment. static final char FRAGMENT_SEPARATOR = '#'; - /** - * The character that should be used for separating query for this URI (; or - * &). - */ + /// The character that should be used for separating query for this URI (; or + /// &). private char querySeparator; - /** - * Flag that identifies if this URI has a scheme and starts with a '/'. - */ + /// Flag that identifies if this URI has a scheme and starts with a '/'. private boolean opaque; - /** - * Flag that identifies if this URI is relative. - */ + /// Flag that identifies if this URI is relative. private boolean absolute; - /** - * The encoded URI string value, without the scheme and fragment. - */ + /// The encoded URI string value, without the scheme and fragment. private String schemeSpecificPart; - /** - * The userinfo, host, and port segment of the URI. - */ + /// The userinfo, host, and port segment of the URI. private String authority; - /** - * The encoded userinfo part of the URI. - */ + /// The encoded userinfo part of the URI. private String userInfo; - /** - * The encoded host value of the URI. - */ + /// The encoded host value of the URI. private String host; - /** - * The URI scheme, or null for opaque URIs. - */ + /// The URI scheme, or null for opaque URIs. private String scheme; - /** - * The encoded path value of the URI. - */ + /// The encoded path value of the URI. private String path; - /** - * The encoded query value of the URI. - */ + /// The encoded query value of the URI. private String query; - /** - * The encoded fragment value of the URI. - */ + /// The encoded fragment value of the URI. private String fragment; - /** - * The port value of the URI, or -1 if no port specified. - */ + /// The port value of the URI, or -1 if no port specified. private int port; - /** - * Constructor to create a new URI object. The userInfo, path, query and - * fragment should be unencoded values - they will be encoded as required. - * - * @param scheme the scheme of the URI (for URLs, this would be the - * protocol), or null for relative URIs. - * @param userInfo the unencoded userinfo segment (ie. username:password) or - * null. - * @param host the hostname or address, or null. - * @param port the host port, or -1. - * @param path the unencoded path segment. - * @param query the unencoded query segment. - * @param fragment the unencoded fragment (often referred to as the - * 'reference' or 'anchor'), or null. - * @throws URISyntaxException if any of the fragments are invalid. - */ + /// Constructor to create a new URI object. The userInfo, path, query and + /// fragment should be unencoded values - they will be encoded as required. + /// + /// #### Parameters + /// + /// - `scheme`: @param scheme the scheme of the URI (for URLs, this would be the + /// protocol), or null for relative URIs. + /// + /// - `userInfo`: @param userInfo the unencoded userinfo segment (ie. username:password) or + /// null. + /// + /// - `host`: the hostname or address, or null. + /// + /// - `port`: the host port, or -1. + /// + /// - `path`: the unencoded path segment. + /// + /// - `query`: the unencoded query segment. + /// + /// - `fragment`: @param fragment the unencoded fragment (often referred to as the + /// 'reference' or 'anchor'), or null. + /// + /// #### Throws + /// + /// - `URISyntaxException`: if any of the fragments are invalid. public URI(String scheme, String userInfo, String host, int port, String path, String query, String fragment) throws URISyntaxException { init(); @@ -188,20 +150,27 @@ public URI(String scheme, String userInfo, String host, int port, String path, S setFragment(fragment, true); } - /** - * Constructor to create a new URI object. The authority, path, query and - * fragment should be unencoded values - they will be encoded as required. - * - * @param scheme the scheme of the URI (for URLs, this would be the - * protocol), or null for relative URIs. - * @param authority the unencoded authority segment (ie. - * username:password@host:port, or simply: host) or null. - * @param path the unencoded path segment. - * @param query the unencoded query segment. - * @param fragment the unencoded fragment (often referred to as the - * 'reference' or 'anchor'), or null. - * @throws URISyntaxException if any of the fragments are invalid. - */ + /// Constructor to create a new URI object. The authority, path, query and + /// fragment should be unencoded values - they will be encoded as required. + /// + /// #### Parameters + /// + /// - `scheme`: @param scheme the scheme of the URI (for URLs, this would be the + /// protocol), or null for relative URIs. + /// + /// - `authority`: @param authority the unencoded authority segment (ie. + /// username:password@host:port, or simply: host) or null. + /// + /// - `path`: the unencoded path segment. + /// + /// - `query`: the unencoded query segment. + /// + /// - `fragment`: @param fragment the unencoded fragment (often referred to as the + /// 'reference' or 'anchor'), or null. + /// + /// #### Throws + /// + /// - `URISyntaxException`: if any of the fragments are invalid. public URI(String scheme, String authority, String path, String query, String fragment) throws URISyntaxException { init(); setScheme(scheme); @@ -211,19 +180,24 @@ public URI(String scheme, String authority, String path, String query, String fr setFragment(fragment, true); } - /** - * Constructor for building URNs. The ssp and fragment should be unencoded - * values - they will be encoded as required. - * - * Examples: mailto:user@codenameone.com sms:+5555551212 tel:+5555551212 - * isbn:9781935182962 - * - * @param scheme - * @param ssp the unencoded scheme specific part (everything except the - * scheme and fragment) - * @param fragment the unencoded fragment, or null - * @throws URISyntaxException if any of the segments are invalid. - */ + /// Constructor for building URNs. The ssp and fragment should be unencoded + /// values - they will be encoded as required. + /// + /// Examples: mailto:user@codenameone.com sms:+5555551212 tel:+5555551212 + /// isbn:9781935182962 + /// + /// #### Parameters + /// + /// - `scheme` + /// + /// - `ssp`: @param ssp the unencoded scheme specific part (everything except the + /// scheme and fragment) + /// + /// - `fragment`: the unencoded fragment, or null + /// + /// #### Throws + /// + /// - `URISyntaxException`: if any of the segments are invalid. public URI(String scheme, String ssp, String fragment) throws URISyntaxException { init(); setScheme(scheme); @@ -231,14 +205,17 @@ public URI(String scheme, String ssp, String fragment) throws URISyntaxException setFragment(fragment, true); } - /** - * Constructor that parses its values from a URI string. This method expects - * all segments to be property encoded by the caller. The URIHelper class - * can be used to encode segments. - * - * @param uriString a full encoded URI in string form to be parsed. - * @throws URISyntaxException if any of the parsed segments are invalid. - */ + /// Constructor that parses its values from a URI string. This method expects + /// all segments to be property encoded by the caller. The URIHelper class + /// can be used to encode segments. + /// + /// #### Parameters + /// + /// - `uriString`: a full encoded URI in string form to be parsed. + /// + /// #### Throws + /// + /// - `URISyntaxException`: if any of the parsed segments are invalid. public URI(String uriString) throws URISyntaxException { if (uriString == null) { throw new URISyntaxException(uriString, "Input is null"); @@ -247,9 +224,7 @@ public URI(String uriString) throws URISyntaxException { parseURI(uriString); } - /** - * Internal - Set the default values. - */ + /// Internal - Set the default values. void init() { absolute = true; querySeparator = QUERY_SEPARATOR; @@ -257,12 +232,12 @@ void init() { port = -1; } - /** - * Utility method - set the scheme, ensuring valid format, and determining - * the query separator to use. - * - * @see http://en.wikipedia.org/wiki/Uniform_resource_name - */ + /// Utility method - set the scheme, ensuring valid format, and determining + /// the query separator to use. + /// + /// #### See also + /// + /// - [http://en.wikipedia.org/wiki/Uniform_resource_name](http://en.wikipedia.org/wiki/Uniform_resource_name) protected void setScheme(String scheme) throws URISyntaxException { if ((this.scheme = scheme) == null) { absolute = false; @@ -276,89 +251,96 @@ protected void setScheme(String scheme) throws URISyntaxException { } } - /** - * Utility method - set the scheme specific part, ensuring valid format. If - * encode=true, then some elements will be run through the encoder (path, - * userinfo, query, fragment), otherwise the elements will be validated for - * proper encoding. - */ + /// Utility method - set the scheme specific part, ensuring valid format. If + /// encode=true, then some elements will be run through the encoder (path, + /// userinfo, query, fragment), otherwise the elements will be validated for + /// proper encoding. protected void setSchemeSpecificPart(String ssp, boolean encode) throws URISyntaxException { parseSchemeSpecificPart(ssp, true); } - /** - * Utility method - set the part, ensuring valid format. If encode=true, - * then some elements will be run through the encoder (path, userinfo, - * query, fragment), otherwise the elements will be validated for proper - * encoding. - */ + /// Utility method - set the part, ensuring valid format. If encode=true, + /// then some elements will be run through the encoder (path, userinfo, + /// query, fragment), otherwise the elements will be validated for proper + /// encoding. protected void setAuthority(String newAuthority, boolean encode) throws URISyntaxException { } - /** - * Utility method to set the query. If parameter encode=true, then the - * result will be encoded, otherwise the result will be validated to ensure - * encoding is valid. Typically the multi-parameter constructors will call - * this method with encode=true, and the single parameter construct will - * pass encode=false. - * - * @param query - * @param encode - * @throws URISyntaxException - */ + /// Utility method to set the query. If parameter encode=true, then the + /// result will be encoded, otherwise the result will be validated to ensure + /// encoding is valid. Typically the multi-parameter constructors will call + /// this method with encode=true, and the single parameter construct will + /// pass encode=false. + /// + /// #### Parameters + /// + /// - `query` + /// + /// - `encode` + /// + /// #### Throws + /// + /// - `URISyntaxException` protected void setQuery(String query, boolean encode) throws URISyntaxException { } - /** - * Utility method to set the path. If parameter encode=true, then the result - * will be encoded, otherwise the result will be validated to ensure - * encoding is valid. Typically the multi-parameter constructors will call - * this method with encode=true, and the single parameter construct will - * pass encode=false. - * - * @param path - * @param encode - * @throws URISyntaxException - */ + /// Utility method to set the path. If parameter encode=true, then the result + /// will be encoded, otherwise the result will be validated to ensure + /// encoding is valid. Typically the multi-parameter constructors will call + /// this method with encode=true, and the single parameter construct will + /// pass encode=false. + /// + /// #### Parameters + /// + /// - `path` + /// + /// - `encode` + /// + /// #### Throws + /// + /// - `URISyntaxException` protected void setPath(String path, boolean encode) throws URISyntaxException { } - /** - * Utility method to construct the authority segment from given host, port, - * and userinfo segments. If parameter encode=true, then the userinfo - * segment will be encoded, otherwise the it will be validated to ensure - * encoding is valid. Typically the multi-parameter constructors will call - * this method with encode=true, and the single parameter construct will - * pass encode=false. - * - * @param host - * @param port - * @param userInfo - * @param encode - * @throws URISyntaxException - */ + /// Utility method to construct the authority segment from given host, port, + /// and userinfo segments. If parameter encode=true, then the userinfo + /// segment will be encoded, otherwise the it will be validated to ensure + /// encoding is valid. Typically the multi-parameter constructors will call + /// this method with encode=true, and the single parameter construct will + /// pass encode=false. + /// + /// #### Parameters + /// + /// - `host` + /// + /// - `port` + /// + /// - `userInfo` + /// + /// - `encode` + /// + /// #### Throws + /// + /// - `URISyntaxException` protected void setAuthority(String host, int port, String userInfo, boolean encode) throws URISyntaxException { } - /** - * Utility method to set the fragment. If parameter encode=true, then the - * result will be encoded, otherwise the result will be validated to ensure - * encoding is valid. Typically the multi-parameter constructors will call - * this method with encode=true, and the single parameter construct will - * pass encode=false. - * - * @param fragment - * @param encode - */ + /// Utility method to set the fragment. If parameter encode=true, then the + /// result will be encoded, otherwise the result will be validated to ensure + /// encoding is valid. Typically the multi-parameter constructors will call + /// this method with encode=true, and the single parameter construct will + /// pass encode=false. + /// + /// #### Parameters + /// + /// - `fragment` + /// + /// - `encode` protected void setFragment(String fragment, boolean encode) { } - /** - * Utility method to construct the scheme specific part from the uri - * segments (less scheme and fragment) - * - * @return - */ + /// Utility method to construct the scheme specific part from the uri + /// segments (less scheme and fragment) protected String rebuildSchemeSpecificPart() { StringBuffer buffer = new StringBuffer(); if (opaque == false && (host != null || port != -1)) { @@ -387,20 +369,23 @@ protected String rebuildSchemeSpecificPart() { return buffer.toString(); } - /** - * A convenience factory method, intended to be used when the URI string is - * known to be valid (ie. a static application URI), so it is not needed for - * the caller to handle invalid syntax. NOTE: this is not away to avoid - * handling errors altogether - passing an invalid URI string will result in - * an IllegalArgumentException being thrown. The benefit here is that the - * compiler will not complain if you don't explicitly handle the error at - * compile time. - * - * When handling a user-editable URI, use the URI constructors instead. - * - * @param uriString URI address as a string - * @return parsed URI object - */ + /// A convenience factory method, intended to be used when the URI string is + /// known to be valid (ie. a static application URI), so it is not needed for + /// the caller to handle invalid syntax. NOTE: this is not away to avoid + /// handling errors altogether - passing an invalid URI string will result in + /// an IllegalArgumentException being thrown. The benefit here is that the + /// compiler will not complain if you don't explicitly handle the error at + /// compile time. + /// + /// When handling a user-editable URI, use the URI constructors instead. + /// + /// #### Parameters + /// + /// - `uriString`: URI address as a string + /// + /// #### Returns + /// + /// parsed URI object public static URI create(String uriString) { URI uri; try { @@ -411,13 +396,16 @@ public static URI create(String uriString) { return uri; } - /** - * Rather than attempting to process the uri string in a linear fashion, - * this implementation works its way from outside-in - * - * @param uriString - * @throws URISyntaxException - */ + /// Rather than attempting to process the uri string in a linear fashion, + /// this implementation works its way from outside-in + /// + /// #### Parameters + /// + /// - `uriString` + /// + /// #### Throws + /// + /// - `URISyntaxException` protected void parseURI(String uriString) throws URISyntaxException { String s = uriString; int index = s.indexOf(FRAGMENT_SEPARATOR); @@ -436,19 +424,23 @@ protected void parseURI(String uriString) throws URISyntaxException { parseSchemeSpecificPart(s, false); } - /** - * Utility method used to parse a given scheme specific part. If parameter - * encode=true, then the result will be encoded, otherwise the result will - * be validated to ensure encoding is valid. Typically the multi-parameter - * constructors will call this method with encode=true, and the single - * parameter construct will pass encode=false. - * - * @param ssp scheme specific part (the URI without the scheme or fragment - * included). - * @param encode true if ssp needs to be encoded, false if ssp needs to be - * verified. - * @throws URISyntaxException if the ssp is invalid. - */ + /// Utility method used to parse a given scheme specific part. If parameter + /// encode=true, then the result will be encoded, otherwise the result will + /// be validated to ensure encoding is valid. Typically the multi-parameter + /// constructors will call this method with encode=true, and the single + /// parameter construct will pass encode=false. + /// + /// #### Parameters + /// + /// - `ssp`: @param ssp scheme specific part (the URI without the scheme or fragment + /// included). + /// + /// - `encode`: @param encode true if ssp needs to be encoded, false if ssp needs to be + /// verified. + /// + /// #### Throws + /// + /// - `URISyntaxException`: if the ssp is invalid. protected void parseSchemeSpecificPart(String ssp, boolean encode) throws URISyntaxException { if (ssp == null) { throw new URISyntaxException(ssp, "Invalid scheme specific part"); @@ -478,15 +470,22 @@ protected void parseSchemeSpecificPart(String ssp, boolean encode) throws URISyn setAuthority(s, encode); } - /** - * Internal utility method to throw a syntax error if a value can not be - * parsed. - * - * @param key name of the value being parsed, for error reporting. - * @param value value to be parsed. - * @return parsed integer. - * @throws URISyntaxException if value can not be parsed. - */ + /// Internal utility method to throw a syntax error if a value can not be + /// parsed. + /// + /// #### Parameters + /// + /// - `key`: name of the value being parsed, for error reporting. + /// + /// - `value`: value to be parsed. + /// + /// #### Returns + /// + /// parsed integer. + /// + /// #### Throws + /// + /// - `URISyntaxException`: if value can not be parsed. int parseIntOption(String key, String value) throws URISyntaxException { try { return Integer.parseInt(value); @@ -495,124 +494,122 @@ int parseIntOption(String key, String value) throws URISyntaxException { } } - /** - * Internal utility method to determine if the given scheme should use - * semicolons (;) for query separator instead of ampersand (&) - */ + /// Internal utility method to determine if the given scheme should use + /// semicolons (;) for query separator instead of ampersand (&) boolean isSocketScheme(String scheme) { return false; } - /** - * Verifies the scheme contains only valid characters as per the URN - * specification (see NID). - * - * @see http://tools.ietf.org/html/rfc2141 - */ + /// Verifies the scheme contains only valid characters as per the URN + /// specification (see NID). + /// + /// #### See also + /// + /// - [http://tools.ietf.org/html/rfc2141](http://tools.ietf.org/html/rfc2141) boolean isValidScheme(String scheme) { return true; } - /** - * Get the scheme part of the URI. - * - * @return the scheme part of the URI. - */ + /// Get the scheme part of the URI. + /// + /// #### Returns + /// + /// the scheme part of the URI. public String getScheme() { return scheme; } - /** - * Get the host name part of the URI. - * - * @return the host name part of the URI. - */ + /// Get the host name part of the URI. + /// + /// #### Returns + /// + /// the host name part of the URI. public String getHost() { return host; } - /** - * Get the port number for this URI. - * - * @return the port number for this URI, or -1 if a port number was not - * specified. - */ + /// Get the port number for this URI. + /// + /// #### Returns + /// + /// @return the port number for this URI, or -1 if a port number was not + /// specified. public int getPort() { return port; } - /** - * Get the decoded path part of the uri. - * - * @return the query part of the URI, or an empty string if no path is - * included in the URI. - */ + /// Get the decoded path part of the uri. + /// + /// #### Returns + /// + /// @return the query part of the URI, or an empty string if no path is + /// included in the URI. public String getPath() { return null; } - /** - * Get the encoded path part of the uri. - * - * @return the query part of the URI, or an empty string if no path is - * included in the URI. - */ + /// Get the encoded path part of the uri. + /// + /// #### Returns + /// + /// @return the query part of the URI, or an empty string if no path is + /// included in the URI. public String getRawPath() { return path; } - /** - * Get the decoded query part of the uri. The query marker (?) itself is not - * included in the result. - * - * @return the query part of the URI. - */ + /// Get the decoded query part of the uri. The query marker (?) itself is not + /// included in the result. + /// + /// #### Returns + /// + /// the query part of the URI. public String getQuery() { return null; } - /** - * Get the encoded query part of the uri. The query marker (?) itself is not - * included in the result. - * - * @return the query part of the URI. - */ + /// Get the encoded query part of the uri. The query marker (?) itself is not + /// included in the result. + /// + /// #### Returns + /// + /// the query part of the URI. public String getRawQuery() { return query; } - /** - * Get the decoded fragment (otherwise known as the "reference" or - * "anchor") part of the uri. The anchor marker (#) itself is not - * included in the result. - * - * @return the anchor part of the URI. - */ + /// Get the decoded fragment (otherwise known as the "reference" or + /// "anchor") part of the uri. The anchor marker (#) itself is not + /// included in the result. + /// + /// #### Returns + /// + /// the anchor part of the URI. public String getFragment() { return null; } - /** - * Get the encoded fragment (otherwise known as the "reference" or - * "anchor") part of the uri. The anchor marker (#) itself is not - * included in the result. - * - * @return the anchor part of the URI. - */ + /// Get the encoded fragment (otherwise known as the "reference" or + /// "anchor") part of the uri. The anchor marker (#) itself is not + /// included in the result. + /// + /// #### Returns + /// + /// the anchor part of the URI. public String getRawFragment() { return fragment; } - /** - * @return the schemeSpecificPart - */ + /// #### Returns + /// + /// the schemeSpecificPart public String getSchemeSpecificPart() { return null; } - /** - * @return the schemeSpecificPart - */ + /// #### Returns + /// + /// the schemeSpecificPart public String getRawSchemeSpecificPart() { if (schemeSpecificPart == null) { schemeSpecificPart = rebuildSchemeSpecificPart(); @@ -620,66 +617,64 @@ public String getRawSchemeSpecificPart() { return schemeSpecificPart; } - /** - * @return the authority - */ + /// #### Returns + /// + /// the authority public String getAuthority() { return null; } - /** - * @return the authority - */ + /// #### Returns + /// + /// the authority public String getRawAuthority() { return authority; } - /** - * @return the userInfo - */ + /// #### Returns + /// + /// the userInfo public String getUserInfo() { return null; } - /** - * @return the userInfo - */ + /// #### Returns + /// + /// the userInfo public String getRawUserInfo() { return userInfo; } - /** - * @return true if this URI has a scheme and starts with a slash - */ + /// #### Returns + /// + /// true if this URI has a scheme and starts with a slash public boolean isOpaque() { return opaque; } - /** - * @return true if the URI is not a relative URI. - */ + /// #### Returns + /// + /// true if the URI is not a relative URI. public boolean isAbsolute() { return absolute; } - /** - * Get the character used for separating query. Normally this will return - * '?'. On J2ME Connector URLs, this method will return ';'. - */ + /// Get the character used for separating query. Normally this will return + /// '?'. On J2ME Connector URLs, this method will return ';'. char getQuerySeparator() { return querySeparator; } - /** - * @return the uri as a string - */ + /// #### Returns + /// + /// the uri as a string public String toString() { return toASCIIString(); } - /** - * @return the uri as a string with parts encoded. - */ + /// #### Returns + /// + /// the uri as a string with parts encoded. public String toASCIIString() { StringBuffer buffer = new StringBuffer(); if (scheme != null) { @@ -692,13 +687,15 @@ public String toASCIIString() { return buffer.toString(); } - /** - * Create a relative URI object against this URI, given the uri parameter. - * - * @param uri - * @return - * @see http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#relativize%28java.net.URI%29 - */ + /// Create a relative URI object against this URI, given the uri parameter. + /// + /// #### Parameters + /// + /// - `uri` + /// + /// #### See also + /// + /// - [http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#relativize%28java.net.URI%29](http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#relativize%28java.net.URI%29) public URI relativize(URI uri) { if (isOpaque() || uri.isOpaque()) { return uri; @@ -726,13 +723,19 @@ public URI relativize(URI uri) { } } - /** - * Resolve a relative URI by merging it with this URI. - * - * @param uri a URI to resolve against this URI. - * @return a new URI created by merging given URI with this URI. - * @see http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#resolve%28java.net.URI%29 - */ + /// Resolve a relative URI by merging it with this URI. + /// + /// #### Parameters + /// + /// - `uri`: a URI to resolve against this URI. + /// + /// #### Returns + /// + /// a new URI created by merging given URI with this URI. + /// + /// #### See also + /// + /// - [http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#resolve%28java.net.URI%29](http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#resolve%28java.net.URI%29) public URI resolve(URI uri) { if (isOpaque() || uri.isAbsolute()) { return uri; @@ -771,12 +774,15 @@ public URI resolve(URI uri) { } - /** - * Normalize a URI by removing any "./" segments, and "path/../" segments. - * - * @return a new URI instance with redundant segments removed. - * @see http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#normalize%28%29 - */ + /// Normalize a URI by removing any "./" segments, and "path/../" segments. + /// + /// #### Returns + /// + /// a new URI instance with redundant segments removed. + /// + /// #### See also + /// + /// - [http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#normalize%28%29](http://docs.oracle.com/javase/6/docs/api/java/net/URI.html#normalize%28%29) public URI normalize() { return null; } diff --git a/Ports/CLDC11/src/java/net/URISyntaxException.java b/Ports/CLDC11/src/java/net/URISyntaxException.java index 7463ca6599..a97475524f 100644 --- a/Ports/CLDC11/src/java/net/URISyntaxException.java +++ b/Ports/CLDC11/src/java/net/URISyntaxException.java @@ -23,30 +23,28 @@ */ package java.net; -/** - * @author Eric Coolman - * - */ +/// @author Eric Coolman public class URISyntaxException extends Exception { private int index; private String input; private String reason; - /** - * - * @param input - * @param reason - */ + /// #### Parameters + /// + /// - `input` + /// + /// - `reason` public URISyntaxException(String input, String reason) { this(input, reason, -1); } - /** - * - * @param input - * @param reason - * @param index - */ + /// #### Parameters + /// + /// - `input` + /// + /// - `reason` + /// + /// - `index` public URISyntaxException(String input, String reason, int index) { super(reason); this.reason = reason; @@ -54,44 +52,44 @@ public URISyntaxException(String input, String reason, int index) { this.input = input; } - /** - * @return the index - */ + /// #### Returns + /// + /// the index public int getIndex() { return index; } - /** - * @param index the index to set - */ + /// #### Parameters + /// + /// - `index`: the index to set void setIndex(int index) { this.index = index; } - /** - * @return the input - */ + /// #### Returns + /// + /// the input public String getInput() { return input; } - /** - * @param input the input to set - */ + /// #### Parameters + /// + /// - `input`: the input to set void setInput(String input) { this.input = input; } - /** - * @return the reason - */ + /// #### Returns + /// + /// the reason public String getReason() { return reason; } - /** - * @param reason the reason to set - */ + /// #### Parameters + /// + /// - `reason`: the reason to set void setReason(String reason) { this.reason = reason; } diff --git a/Ports/CLDC11/src/java/nio/charset/Charset.java b/Ports/CLDC11/src/java/nio/charset/Charset.java index 1da3a2b4d1..b7618758e4 100644 --- a/Ports/CLDC11/src/java/nio/charset/Charset.java +++ b/Ports/CLDC11/src/java/nio/charset/Charset.java @@ -22,10 +22,8 @@ */ package java.nio.charset; -/** - * Added this for Kotlin - * @author shannah - */ +/// Added this for Kotlin +/// @author shannah public class Charset implements Comparable { private String name; diff --git a/Ports/CLDC11/src/java/nio/charset/StandardCharsets.java b/Ports/CLDC11/src/java/nio/charset/StandardCharsets.java index e0dccfea90..8b094883b0 100644 --- a/Ports/CLDC11/src/java/nio/charset/StandardCharsets.java +++ b/Ports/CLDC11/src/java/nio/charset/StandardCharsets.java @@ -9,9 +9,7 @@ */ package java.nio.charset; -/** - * Minimal charset constants supported by CLDC11 stubs. - */ +/// Minimal charset constants supported by CLDC11 stubs. public final class StandardCharsets { private StandardCharsets() { } diff --git a/Ports/CLDC11/src/java/text/DateFormat.java b/Ports/CLDC11/src/java/text/DateFormat.java index 4825e56129..6c9c55049e 100644 --- a/Ports/CLDC11/src/java/text/DateFormat.java +++ b/Ports/CLDC11/src/java/text/DateFormat.java @@ -25,185 +25,220 @@ import java.util.Date; -/** - * A class for parsing and formatting localisation sensitive dates, compatible - * with Jave 6 SDK. This implementation uses the Codename One localization manager for handling formatting dates. Parsing - * dates is not implemented in this class since the localization pattern is not - * exposed. - * - * @author Eric Coolman - * @see http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html - * @deprecated this class has many issues in iOS and other platforms, please use the L10NManager - */ +/// A class for parsing and formatting localisation sensitive dates, compatible +/// with Jave 6 SDK. This implementation uses the Codename One localization manager for handling formatting dates. Parsing +/// dates is not implemented in this class since the localization pattern is not +/// exposed. +/// +/// @author Eric Coolman +/// +/// #### Deprecated +/// +/// this class has many issues in iOS and other platforms, please use the L10NManager +/// +/// #### See also +/// +/// - [http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html](http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html) public class DateFormat extends Format { - /** - * Constant for full style parsing/formatting pattern. - */ + /// Constant for full style parsing/formatting pattern. public static final int FULL = 0; - /** - * Constant for long style parsing/formatting pattern. - */ + /// Constant for long style parsing/formatting pattern. public static final int LONG = 1; - /** - * Constant for medium style parsing/formatting pattern. - */ + /// Constant for medium style parsing/formatting pattern. public static final int MEDIUM = 2; - /** - * Constant for short style parsing/formatting pattern. - */ + /// Constant for short style parsing/formatting pattern. public static final int SHORT = 3; - /** - * Constant for default style (MEDIUM) parsing/formatting pattern. - */ + /// Constant for default style (MEDIUM) parsing/formatting pattern. public static final int DEFAULT = MEDIUM; private int dateStyle; private int timeStyle; - /** - * Construct a date formatter using default patterns for date and time (SHORT/SHORT). - */ + /// Construct a date formatter using default patterns for date and time (SHORT/SHORT). DateFormat() { this(SHORT, SHORT); } - /** - * - */ + /// DateFormat(int dateStyle, int timeStyle) { this.dateStyle = dateStyle; this.timeStyle = timeStyle; } - /** - * Format a given object. - * - * @obj object to be formatted. - * @return formatted object. - * @throws IllegalArgumentException of the source can not be formatted. - */ + /// Format a given object. + /// + /// @obj object to be formatted. + /// + /// #### Returns + /// + /// formatted object. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: of the source can not be formatted. @Override public String format(Object obj) throws IllegalArgumentException { return format(obj, new StringBuffer()); } - /** - * Format a given object. - * - * @param source object to be formatted. - * @param toAppendTo buffer to which to append output. - * @return formatted date. - * @throws IllegalArgumentException of the source can not be formatted. - */ + /// Format a given object. + /// + /// #### Parameters + /// + /// - `source`: object to be formatted. + /// + /// - `toAppendTo`: buffer to which to append output. + /// + /// #### Returns + /// + /// formatted date. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: of the source can not be formatted. String format(Object obj, StringBuffer toAppendTo) throws IllegalArgumentException { return null; } - /** - * Format a given date. - * - * @param source date to be formatted. - * @return formatted date. - */ + /// Format a given date. + /// + /// #### Parameters + /// + /// - `source`: date to be formatted. + /// + /// #### Returns + /// + /// formatted date. public String format(Date source) { return format(source, new StringBuffer()); } - /** - * Format a given date. - * - * @param source date to be formatted. - * @param toAppendTo buffer to which to append output. - * @return formatted date. - */ + /// Format a given date. + /// + /// #### Parameters + /// + /// - `source`: date to be formatted. + /// + /// - `toAppendTo`: buffer to which to append output. + /// + /// #### Returns + /// + /// formatted date. String format(Date source, StringBuffer toAppendTo) { return null; } - /** - * NOT IMPLEMENTED - use SimpleDateFormat for parsing instead. - */ + /// NOT IMPLEMENTED - use SimpleDateFormat for parsing instead. @Override public Object parseObject(String source) throws ParseException { // can't parse because we don't know the L10NManagers templates throw new ParseException("Not implemented", 0); } - /** - * NOT IMPLEMENTED - use SimpleDateFormat for parsing instead. - */ + /// NOT IMPLEMENTED - use SimpleDateFormat for parsing instead. public Date parse(String source) throws ParseException { return (Date) parseObject(source); } - /** - * Get a DateFormat instance with default style for date/time (SHORT/SHORT). - * @return a DateFormat instance. - */ + /// Get a DateFormat instance with default style for date/time (SHORT/SHORT). + /// + /// #### Returns + /// + /// a DateFormat instance. public static final DateFormat getInstance() { return getDateTimeInstance(SHORT, SHORT); } - /** - * Get a DateFormat instance with default style for date (SHORT). - * @return a DateFormat instance. - */ + /// Get a DateFormat instance with default style for date (SHORT). + /// + /// #### Returns + /// + /// a DateFormat instance. public static final DateFormat getDateInstance() { return getDateInstance(SHORT); } - /** - * Get a DateFormat instance with default style for time (SHORT). - * @return a DateFormat instance. - */ + /// Get a DateFormat instance with default style for time (SHORT). + /// + /// #### Returns + /// + /// a DateFormat instance. public static final DateFormat getTimeInstance() { return getTimeInstance(SHORT); } - /** - * Get a DateFormat instance that uses a given style for dates. - * - * @param style style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); - * @return a DateFormat instance. - * @see #SHORT - * @see #MEDIUM - * @see #LONG - * @see #FULL - * @see #DEFAULT - */ + /// Get a DateFormat instance that uses a given style for dates. + /// + /// #### Parameters + /// + /// - `style`: style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); + /// + /// #### Returns + /// + /// a DateFormat instance. + /// + /// #### See also + /// + /// - #SHORT + /// + /// - #MEDIUM + /// + /// - #LONG + /// + /// - #FULL + /// + /// - #DEFAULT public static final DateFormat getDateInstance(int style) { return getDateTimeInstance(style, DEFAULT); } - /** - * Get a DateFormat instance that uses a given style for times. - * - * @param style style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); - * @return a DateFormat instance. - * @see #SHORT - * @see #MEDIUM - * @see #LONG - * @see #FULL - * @see #DEFAULT - */ + /// Get a DateFormat instance that uses a given style for times. + /// + /// #### Parameters + /// + /// - `style`: style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); + /// + /// #### Returns + /// + /// a DateFormat instance. + /// + /// #### See also + /// + /// - #SHORT + /// + /// - #MEDIUM + /// + /// - #LONG + /// + /// - #FULL + /// + /// - #DEFAULT public static final DateFormat getTimeInstance(int style) { return getDateTimeInstance(DEFAULT, style); } - /** - * Get a DateFormat instance that uses a given style for dates and times. - * - * @param style style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); - * @return a DateFormat instance. - * @see #SHORT - * @see #MEDIUM - * @see #LONG - * @see #FULL - * @see #DEFAULT - */ + /// Get a DateFormat instance that uses a given style for dates and times. + /// + /// #### Parameters + /// + /// - `style`: style to use for parsing and formatting (SHORT, MEDIUM, LONG, FULL, DEFAULT); + /// + /// #### Returns + /// + /// a DateFormat instance. + /// + /// #### See also + /// + /// - #SHORT + /// + /// - #MEDIUM + /// + /// - #LONG + /// + /// - #FULL + /// + /// - #DEFAULT public static final DateFormat getDateTimeInstance(int dateStyle, int timeStyle) { return new DateFormat(dateStyle, timeStyle); } diff --git a/Ports/CLDC11/src/java/text/DateFormatPatterns.java b/Ports/CLDC11/src/java/text/DateFormatPatterns.java index 71b29954e1..c1c7eb3415 100644 --- a/Ports/CLDC11/src/java/text/DateFormatPatterns.java +++ b/Ports/CLDC11/src/java/text/DateFormatPatterns.java @@ -22,43 +22,24 @@ */ package java.text; -/** - * Common patterns for dates, times, and timestamps. - * - * @author Eric Coolman - * - */ +/// Common patterns for dates, times, and timestamps. +/// +/// @author Eric Coolman class DateFormatPatterns { - /** - * Pattern for parsing/formatting RFC-2822 timestamp. - */ + /// Pattern for parsing/formatting RFC-2822 timestamp. public static final String RFC2822 = "EEE, dd MMM yyyy HH:mm:ss Z"; - /** - * Pattern for parsing/formatting RFC-822 timestamp. - */ + /// Pattern for parsing/formatting RFC-822 timestamp. public static final String RFC822 = RFC2822; - /** - * Pattern for parsing/formatting ISO8601 timestamp. - */ + /// Pattern for parsing/formatting ISO8601 timestamp. public static final String ISO8601 = "yyyy-MM-dd'T'HH:mm:ssZ"; - /** - * Pattern for parsing/formatting Twitter timeline timestamp. - */ + /// Pattern for parsing/formatting Twitter timeline timestamp. public static final String TWITTER_TIMELINE = "EEE MMM dd HH:mm:ss ZZZ yyyy"; - /** - * Pattern for parsing/formatting Twitter search timestamp. - */ + /// Pattern for parsing/formatting Twitter search timestamp. public static final String TWITTER_SEARCH = "EEE, dd MMM yyyy HH:mm:ss Z"; - /** - * Pattern for a verbose date - */ + /// Pattern for a verbose date public static final String VERBOSE_DATE = "EEEE, MMM dd, yyyy"; - /** - * Pattern for a verbose time - */ + /// Pattern for a verbose time public static final String VERBOSE_TIME = "HH:mm:ssaa z"; - /** - * Pattern for a verbose timestamp - */ + /// Pattern for a verbose timestamp public static final String VERBOSE_TIMESTAMP = VERBOSE_DATE + ", " + VERBOSE_TIME; } diff --git a/Ports/CLDC11/src/java/text/DateFormatSymbols.java b/Ports/CLDC11/src/java/text/DateFormatSymbols.java index 48c4ecfe1e..6bd1e0df4d 100644 --- a/Ports/CLDC11/src/java/text/DateFormatSymbols.java +++ b/Ports/CLDC11/src/java/text/DateFormatSymbols.java @@ -25,10 +25,7 @@ import java.util.Hashtable; import java.util.TimeZone; -/** - * @author Eric Coolman - * - */ +/// @author Eric Coolman public class DateFormatSymbols implements Cloneable { static final int ZONE_ID = 0; static final int ZONE_LONGNAME = 1; diff --git a/Ports/CLDC11/src/java/text/Format.java b/Ports/CLDC11/src/java/text/Format.java index 2a5b97c075..047ea37987 100644 --- a/Ports/CLDC11/src/java/text/Format.java +++ b/Ports/CLDC11/src/java/text/Format.java @@ -22,28 +22,41 @@ */ package java.text; -/** - * An abstract class for parsing and formatting localisation sensitive information, compatible with JDK 6. - * - * @see http://docs.oracle.com/javase/6/docs/api/java/text/Format.html - * @author Eric Coolman - */ +/// An abstract class for parsing and formatting localisation sensitive information, compatible with JDK 6. +/// +/// @author Eric Coolman +/// +/// #### See also +/// +/// - [http://docs.oracle.com/javase/6/docs/api/java/text/Format.html](http://docs.oracle.com/javase/6/docs/api/java/text/Format.html) public abstract class Format implements Cloneable { - /** - * Format an object. - * - * @param source object to be formatted to text. - * @return formatted text. - * @throws IllegalArgumentException if the source can not be formatted. - */ + /// Format an object. + /// + /// #### Parameters + /// + /// - `source`: object to be formatted to text. + /// + /// #### Returns + /// + /// formatted text. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if the source can not be formatted. public abstract String format(Object source) throws IllegalArgumentException; - /** - * Parse an string to an object. - * - * @param source document to be parsed. - * @return parsed object. - * @throws ParseException if the source could not be parsed. - */ + /// Parse an string to an object. + /// + /// #### Parameters + /// + /// - `source`: document to be parsed. + /// + /// #### Returns + /// + /// parsed object. + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. public abstract Object parseObject(String source) throws ParseException; } \ No newline at end of file diff --git a/Ports/CLDC11/src/java/text/ParseException.java b/Ports/CLDC11/src/java/text/ParseException.java index 835d678a6e..ffa2965511 100644 --- a/Ports/CLDC11/src/java/text/ParseException.java +++ b/Ports/CLDC11/src/java/text/ParseException.java @@ -22,43 +22,40 @@ */ package java.text; -/** - * An error occurred during parsing. - * - * @author Eric Coolman - * - */ +/// An error occurred during parsing. +/// +/// @author Eric Coolman public class ParseException extends Exception { private int errorOffset; private Throwable causedBy; - /** - * @param errorOffset - */ + /// #### Parameters + /// + /// - `errorOffset` public ParseException(String s, int errorOffset) { super(s); this.errorOffset = errorOffset; } - /** - * @param errorOffset - */ + /// #### Parameters + /// + /// - `errorOffset` ParseException(Throwable causedBy, String s, int errorOffset) { super((s == null && causedBy != null) ? causedBy.getMessage() : s); this.causedBy = causedBy; this.errorOffset = errorOffset; } - /** - * @return the errorOffset - */ + /// #### Returns + /// + /// the errorOffset public int getErrorOffset() { return errorOffset; } - /** - * @return the causedBy - */ + /// #### Returns + /// + /// the causedBy Throwable getCausedBy() { return causedBy; } diff --git a/Ports/CLDC11/src/java/text/SimpleDateFormat.java b/Ports/CLDC11/src/java/text/SimpleDateFormat.java index 46e9c519a4..82437143db 100644 --- a/Ports/CLDC11/src/java/text/SimpleDateFormat.java +++ b/Ports/CLDC11/src/java/text/SimpleDateFormat.java @@ -28,178 +28,118 @@ import java.util.TimeZone; import java.util.Vector; -/** - * A class for parsing and formatting dates with a given pattern, compatible - * with the Java 6 API. - * - * @see http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html - * @author Eric Coolman - * @deprecated this class has many issues in iOS and other platforms, please use the L10NManager - */ +/// A class for parsing and formatting dates with a given pattern, compatible +/// with the Java 6 API. +/// +/// @author Eric Coolman +/// +/// #### Deprecated +/// +/// this class has many issues in iOS and other platforms, please use the L10NManager +/// +/// #### See also +/// +/// - [http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html](http://docs.oracle.com/javase/6/docs/api/java/text/DateFormat.html) public class SimpleDateFormat extends DateFormat { - /** - * Pattern character for ERA (ie. BC, AD). - */ + /// Pattern character for ERA (ie. BC, AD). private static final char ERA_LETTER = 'G'; - /** - * Pattern character for year. - */ + /// Pattern character for year. private static final char YEAR_LETTER = 'y'; - /** - * Pattern character for month. - */ + /// Pattern character for month. private static final char MONTH_LETTER = 'M'; - /** - * Pattern character for week in year. - */ + /// Pattern character for week in year. private static final char WEEK_IN_YEAR_LETTER = 'w'; - /** - * Pattern character for week in month. - */ + /// Pattern character for week in month. private static final char WEEK_IN_MONTH_LETTER = 'W'; - /** - * Pattern character for day in year. - */ + /// Pattern character for day in year. private static final char DAY_IN_YEAR_LETTER = 'D'; - /** - * Pattern character for day. - */ + /// Pattern character for day. private static final char DAY_LETTER = 'd'; - /** - * Pattern character for day-of-week in month. - */ + /// Pattern character for day-of-week in month. private static final char DOW_IN_MONTH_LETTER = 'F'; - /** - * Pattern character for day of week. - */ + /// Pattern character for day of week. private static final char DAY_OF_WEEK_LETTER = 'E'; - /** - * Pattern character for am/pm. - */ + /// Pattern character for am/pm. private static final char AMPM_LETTER = 'a'; - /** - * Pattern character for hour (0-23). - */ + /// Pattern character for hour (0-23). private static final char HOUR_LETTER = 'H'; - /** - * Pattern character for 1-based hour (1-24). - */ + /// Pattern character for 1-based hour (1-24). private static final char HOUR_1_LETTER = 'k'; - /** - * Pattern character for 12-hour (0-11). - */ + /// Pattern character for 12-hour (0-11). private static final char HOUR12_LETTER = 'K'; - /** - * Pattern character for 1-based 12-hour (1-12). - */ + /// Pattern character for 1-based 12-hour (1-12). private static final char HOUR12_1_LETTER = 'h'; - /** - * Pattern character for minute. - */ + /// Pattern character for minute. private static final char MINUTE_LETTER = 'm'; - /** - * Pattern character for second. - */ + /// Pattern character for second. private static final char SECOND_LETTER = 's'; - /** - * Pattern character for millisecond. - */ + /// Pattern character for millisecond. private static final char MILLISECOND_LETTER = 'S'; - /** - * Pattern character for general timezone. - */ + /// Pattern character for general timezone. private static final char TIMEZONE_LETTER = 'z'; - /** - * Pattern character for RFC 822-style timezone. - */ + /// Pattern character for RFC 822-style timezone. private static final char TIMEZONE822_LETTER = 'Z'; - /** - * Internally used character for literal text. - */ + /// Internally used character for literal text. private static final char LITERAL_LETTER = '*'; - /** - * Pattern character for starting/ending literal text explicitly in pattern. - */ + /// Pattern character for starting/ending literal text explicitly in pattern. private static final char EXPLICIT_LITERAL = '\''; - /** - * positive sign - */ + /// positive sign private static final char SIGN_POSITIVE = '+'; - /** - * negative sign - */ + /// negative sign private static final char SIGN_NEGATIVE = '-'; - /** - * The number of milliseconds in a minute. - */ + /// The number of milliseconds in a minute. private static final int MILLIS_TO_MINUTES = 60000; - /** - * Pattern characters recognised by this implementation (same as JDK 1.6). - */ + /// Pattern characters recognised by this implementation (same as JDK 1.6). private static final String PATTERN_LETTERS = "adDEFGHhKkMmsSwWyzZ"; - /** - * TimeZone ID for Greenwich Mean Time - */ + /// TimeZone ID for Greenwich Mean Time private static final String GMT = "GMT"; - /** - * This is missing from the Codename One Calendar object, but required by - * TimeZone.getOffset() - */ + /// This is missing from the Codename One Calendar object, but required by + /// TimeZone.getOffset() private static final int ERA = 0; - /** - * More missing from the calendar object - being lower field values, it is - * likely they do exist on the devices Calendar object, if they don't, certain - * lesser-used letters will not work in a pattern. - */ + /// More missing from the calendar object - being lower field values, it is + /// likely they do exist on the devices Calendar object, if they don't, certain + /// lesser-used letters will not work in a pattern. private static final int WEEK_OF_MONTH = 4; private static final int WEEK_OF_YEAR = 3; private static final int DAY_OF_WEEK_IN_MONTH = 8; private static final int DAY_OF_YEAR = 6; - /** - * Localisation sensitive symbols used for handling text components. - */ + /// Localisation sensitive symbols used for handling text components. private DateFormatSymbols dateFormatSymbols; - /** - * The user-supplied pattern - */ + /// The user-supplied pattern private String pattern; - /** - * The parsed pattern - */ + /// The parsed pattern private List patternTokens; - /** - * Construct a SimpleDateFormat with no pattern. - */ + /// Construct a SimpleDateFormat with no pattern. public SimpleDateFormat() { super(); } - /** - * Construct a SimpleDateFormat with a given pattern. - * - * @param pattern - */ + /// Construct a SimpleDateFormat with a given pattern. + /// + /// #### Parameters + /// + /// - `pattern` public SimpleDateFormat(String pattern) { super(); this.pattern = pattern; } - /** - * @return the pattern - */ + /// #### Returns + /// + /// the pattern public String toPattern() { return pattern; } - /** - * Get the date format symbols for parsing/formatting textual components of - * dates in a localization sensitive way. - * - * @return current symbols. - */ + /// Get the date format symbols for parsing/formatting textual components of + /// dates in a localization sensitive way. + /// + /// #### Returns + /// + /// current symbols. public DateFormatSymbols getDateFormatSymbols() { if (dateFormatSymbols == null) { dateFormatSymbols = new DateFormatSymbols(); @@ -207,21 +147,21 @@ public DateFormatSymbols getDateFormatSymbols() { return dateFormatSymbols; } - /** - * Apply new date format symbols for parsing/formatting textual components - * of dates in a localisation sensitive way. - * - * @param newSymbols new format symbols. - */ + /// Apply new date format symbols for parsing/formatting textual components + /// of dates in a localisation sensitive way. + /// + /// #### Parameters + /// + /// - `newSymbols`: new format symbols. public void setDateFormatSymbols(DateFormatSymbols newSymbols) { dateFormatSymbols = newSymbols; } - /** - * Apply a new pattern. - * - * @param pattern the pattern to set - */ + /// Apply a new pattern. + /// + /// #### Parameters + /// + /// - `pattern`: the pattern to set public void applyPattern(String pattern) { this.pattern = pattern; if (patternTokens != null) { @@ -230,11 +170,7 @@ public void applyPattern(String pattern) { } } - /** - * G - * - * @return - */ + /// G List getPatternTokens() { if (this.patternTokens == null) { patternTokens = parseDatePattern(pattern); @@ -534,52 +470,68 @@ public Date parse(String source) throws ParseException { return calendar.getTime(); } - /** - * Parse a hour value. Depending on patternChar parameter, the hour can be - * 0-23, 1-24, 0-11, or 1-12. The returned value will always be 0 based. - * - * @param year as a string. - * @param offset the offset of original timestamp where marker started, for - * error reporting. - * @return full year. - * @throws ParseException if the source could not be parsed. - * @see http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html - */ + /// Parse a hour value. Depending on patternChar parameter, the hour can be + /// 0-23, 1-24, 0-11, or 1-12. The returned value will always be 0 based. + /// + /// #### Parameters + /// + /// - `year`: as a string. + /// + /// - `offset`: @param offset the offset of original timestamp where marker started, for + /// error reporting. + /// + /// #### Returns + /// + /// full year. + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. + /// + /// #### See also + /// + /// - [http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html](http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) int parseHour(String source, char patternChar, int offset) throws ParseException { int min = (patternChar == HOUR_1_LETTER || patternChar == HOUR12_1_LETTER) ? 1 : 0; int max = ((patternChar == HOUR_LETTER || patternChar == HOUR_1_LETTER) ? 23 : 11) + min; return parseNumber(source, offset, "hour", min, max) - min; } - /** - * Utility method to validate a number is within given range. - */ + /// Utility method to validate a number is within given range. void validateNumber(int i, int ofs, String name, int min, int max) throws ParseException { if (i < min || i > max) { throwInvalid(name, ofs); } } - /** - * Utility method to keep parsing errors consistent. - * - * @param name name of the element being parsed when error occurred. - * @param offset offset within the original timestamp where named element - * beings. - */ + /// Utility method to keep parsing errors consistent. + /// + /// #### Parameters + /// + /// - `name`: name of the element being parsed when error occurred. + /// + /// - `offset`: @param offset offset within the original timestamp where named element + /// beings. int throwInvalid(String name, int offset) throws ParseException { throw new ParseException("Invalid " + name + " value", offset); } - /** - * Parse a numeric value, validating against given min/max constraints. - * - * @param number as a string. - * @param offset the offset of original timestamp where number starts, for - * error reporting. - * @return numeric value as an int - * @throws ParseException if the source could not be parsed. - */ + /// Parse a numeric value, validating against given min/max constraints. + /// + /// #### Parameters + /// + /// - `number`: as a string. + /// + /// - `offset`: @param offset the offset of original timestamp where number starts, for + /// error reporting. + /// + /// #### Returns + /// + /// numeric value as an int + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. int parseNumber(String source, int ofs, String name, int min, int max) throws ParseException { if (source == null) { throwInvalid(name, ofs); @@ -596,55 +548,67 @@ int parseNumber(String source, int ofs, String name, int min, int max) throws Pa return v; } - /** - * Determine the number of minutes to adjust the date for local DST. This - * should provide a historically correct value, also accounting for changes - * in GMT offset. See TimeZone javadoc for more details. - * - * @param calendar - * @return - */ + /// Determine the number of minutes to adjust the date for local DST. This + /// should provide a historically correct value, also accounting for changes + /// in GMT offset. See TimeZone javadoc for more details. + /// + /// #### Parameters + /// + /// - `calendar` int getDSTOffset(Calendar source) { TimeZone localTimezone = Calendar.getInstance().getTimeZone(); int rawOffset = localTimezone.getRawOffset() / MILLIS_TO_MINUTES; return getOffsetInMinutes(source, localTimezone) - rawOffset; } - /** - * Get the offset from GMT for a given timezone. - * - * @param source - * @param timezone - * @return - */ + /// Get the offset from GMT for a given timezone. + /// + /// #### Parameters + /// + /// - `source` + /// + /// - `timezone` int getOffsetInMinutes(Calendar source, TimeZone timezone) { return timezone.getOffset(source.get(ERA), source.get(Calendar.YEAR), source.get(Calendar.MONTH), source.get(Calendar.DAY_OF_MONTH), source.get(Calendar.DAY_OF_WEEK), source.get(Calendar.MILLISECOND)) / MILLIS_TO_MINUTES; } - /** - * Read an unparsable text string. - * - * @param source full timestamp - * @param ofs offset within timestamp where text starts - * @return the text - */ + /// Read an unparsable text string. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where text starts + /// + /// #### Returns + /// + /// the text String readLiteral(String source, int ofs, String token) { return source.substring(ofs, ofs + token.length()); } - /** - * Read the number. Does not attempt to parse. - * - * @param source full timestamp - * @param ofs offset within timestamp where number starts - * @param token the token currently being parsed - * @param adjacent true if the number is adjacent to next field with no - * literal separator. - * @return the number as a string, or null if could not read. - * @see #parseNumber(String, int, String, int, int) - */ + /// Read the number. Does not attempt to parse. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where number starts + /// + /// - `token`: the token currently being parsed + /// + /// - `adjacent`: @param adjacent true if the number is adjacent to next field with no + /// literal separator. + /// + /// #### Returns + /// + /// the number as a string, or null if could not read. + /// + /// #### See also + /// + /// - #parseNumber(String, int, String, int, int) String readNumber(String source, int ofs, String token, boolean adjacent) { if (adjacent) { return source.substring(ofs, ofs + token.length()); @@ -663,21 +627,31 @@ String readNumber(String source, int ofs, String token, boolean adjacent) { return source.substring(ofs); } - /** - * Parse a year value. If the year is a two digit value, if the value is - * within 20 years ahead of the current year, current century will be used - * (ie. if current year is 2013, a value of "33" will return 2033), - * otherwise previous century is used (ie. with current year of 2012, a - * value of 97 will return "1997"). See Java 6 documentation for more - * details of this algorithm. - * - * @param year as a string. - * @param offset the offset of original timestamp where marker started, for - * error reporting. - * @return full year. - * @throws ParseException if the source could not be parsed. - * @see http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html - */ + /// Parse a year value. If the year is a two digit value, if the value is + /// within 20 years ahead of the current year, current century will be used + /// (ie. if current year is 2013, a value of "33" will return 2033), + /// otherwise previous century is used (ie. with current year of 2012, a + /// value of 97 will return "1997"). See Java 6 documentation for more + /// details of this algorithm. + /// + /// #### Parameters + /// + /// - `year`: as a string. + /// + /// - `offset`: @param offset the offset of original timestamp where marker started, for + /// error reporting. + /// + /// #### Returns + /// + /// full year. + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. + /// + /// #### See also + /// + /// - [http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html](http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html) int parseYear(String source, String token, int ofs) throws ParseException { int year = parseNumber(source, ofs, "year", -1, -1); int len = source.length(); @@ -694,13 +668,17 @@ int parseYear(String source, String token, int ofs) throws ParseException { return year; } - /** - * Read the day of week string. Does not attempt to parse. - * - * @param source full timestamp - * @param ofs offset within timestamp where day of week starts - * @return the day of week as a string, or null if could not read. - */ + /// Read the day of week string. Does not attempt to parse. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where day of week starts + /// + /// #### Returns + /// + /// the day of week as a string, or null if could not read. String readDayOfWeek(String source, int ofs) { int i = findEndText(source, ofs); if (i == -1) { @@ -720,14 +698,21 @@ String readDayOfWeek(String source, int ofs) { return null; } - /** - * Read the am/pm marker string. Does not attempt to parse. - * - * @param source full timestamp - * @param ofs offset within timestamp where marker starts - * @return the marker as a string, or null if could not read. - * @see #parseAmPmMarker(String, int) - */ + /// Read the am/pm marker string. Does not attempt to parse. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where marker starts + /// + /// #### Returns + /// + /// the marker as a string, or null if could not read. + /// + /// #### See also + /// + /// - #parseAmPmMarker(String, int) String readAmPmMarker(String source, int ofs) { int i = findEndText(source, ofs); if (i == -1) { @@ -748,17 +733,27 @@ String readAmPmMarker(String source, int ofs) { return null; } - /** - * Parse an AM/PM marker. The source marker can be the marker name as - * defined in DateFormatSymbols, or the first character of the marker name. - * - * @param month as a string. - * @param offset the offset of original timestamp where marker started, for - * error reporting. - * @return Calendar.AM or Calendar.PM - * @see DateFormatSymbols - * @throws ParseException if the source could not be parsed. - */ + /// Parse an AM/PM marker. The source marker can be the marker name as + /// defined in DateFormatSymbols, or the first character of the marker name. + /// + /// #### Parameters + /// + /// - `month`: as a string. + /// + /// - `offset`: @param offset the offset of original timestamp where marker started, for + /// error reporting. + /// + /// #### Returns + /// + /// Calendar.AM or Calendar.PM + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. + /// + /// #### See also + /// + /// - DateFormatSymbols int parseAmPmMarker(String source, int ofs) throws ParseException { String markers[] = getDateFormatSymbols().getAmPmStrings(); for (int i = 0; i < markers.length; i++) { @@ -776,14 +771,21 @@ int parseAmPmMarker(String source, int ofs) throws ParseException { return throwInvalid("am/pm marker", ofs); } - /** - * Read the month string. Does not attempt to parse. - * - * @param source full timestamp - * @param ofs offset within timestamp where month starts - * @return the month as a string, or null if could not read. - * @see #parseMonth(String, int) - */ + /// Read the month string. Does not attempt to parse. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where month starts + /// + /// #### Returns + /// + /// the month as a string, or null if could not read. + /// + /// #### See also + /// + /// - #parseMonth(String, int) String readMonth(String source, int ofs, String token, boolean adjacent) { if (token.length() < 3) { if (adjacent) { @@ -811,18 +813,28 @@ String readMonth(String source, int ofs, String token, boolean adjacent) { return null; } - /** - * Parse a month value to an offset from Calendar.JANUARY. The source month - * value can be numeric (1-12), a shortform or longform month name as - * defined in DateFormatSymbols. - * - * @param month as a string. - * @param offset the offset of original timestamp where month started, for - * error reporting. - * @return month as an offset from Calendar.JANUARY. - * @see DateFormatSymbols - * @throws ParseException if the source could not be parsed. - */ + /// Parse a month value to an offset from Calendar.JANUARY. The source month + /// value can be numeric (1-12), a shortform or longform month name as + /// defined in DateFormatSymbols. + /// + /// #### Parameters + /// + /// - `month`: as a string. + /// + /// - `offset`: @param offset the offset of original timestamp where month started, for + /// error reporting. + /// + /// #### Returns + /// + /// month as an offset from Calendar.JANUARY. + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. + /// + /// #### See also + /// + /// - DateFormatSymbols int parseMonth(String month, int offset) throws ParseException { if (month.length() < 3) { return (parseNumber(month, offset, "month", 1, 12) - 1) + Calendar.JANUARY; @@ -842,14 +854,21 @@ int parseMonth(String month, int offset) throws ParseException { return throwInvalid("month", offset); } - /** - * Read the timezone string. Does not attempt to parse. - * - * @param source full timestamp - * @param ofs offset within timestamp where timezone starts - * @return the timezone as a string or null if error reading. - * @see #parseTimeZone(String) - */ + /// Read the timezone string. Does not attempt to parse. + /// + /// #### Parameters + /// + /// - `source`: full timestamp + /// + /// - `ofs`: offset within timestamp where timezone starts + /// + /// #### Returns + /// + /// the timezone as a string or null if error reading. + /// + /// #### See also + /// + /// - #parseTimeZone(String) String readTimeZone(String source, int ofs) { int sp = source.indexOf(' ', ofs); String fragment; @@ -881,17 +900,24 @@ String readTimeZone(String source, int ofs) { return null; } - /** - * Parse the timezone to an offset from GMT in minutes. The source can be - * RFC-822 (ie. -0400), ISO8601 (ie. GMT+08:50), or TimeZone ID (ie. PDT, - * America/New_York, etc). This method does not adjust for DST. - * - * @param source source timezone. - * @param offset the offset of original timestamp where month started, for - * error reporting. - * @return offset from GMT in minutes. - * @throws ParseException if the source could not be parsed. - */ + /// Parse the timezone to an offset from GMT in minutes. The source can be + /// RFC-822 (ie. -0400), ISO8601 (ie. GMT+08:50), or TimeZone ID (ie. PDT, + /// America/New_York, etc). This method does not adjust for DST. + /// + /// #### Parameters + /// + /// - `source`: source timezone. + /// + /// - `offset`: @param offset the offset of original timestamp where month started, for + /// error reporting. + /// + /// #### Returns + /// + /// offset from GMT in minutes. + /// + /// #### Throws + /// + /// - `ParseException`: if the source could not be parsed. int parseTimeZone(String source, int ofs) throws ParseException { char tzSign = source.charAt(0); // handle RFC822 style GMT offset (-0500) @@ -934,13 +960,17 @@ int parseTimeZone(String source, int ofs) throws ParseException { return throwInvalid("timezone", ofs); } - /** - * Attempt to find the end of a field if the length is not known. - * - * @param source the full source timestamp - * @param ofs index of where current field starts. - * @return the index of the end of field, or -1 if couldn't determine. - */ + /// Attempt to find the end of a field if the length is not known. + /// + /// #### Parameters + /// + /// - `source`: the full source timestamp + /// + /// - `ofs`: index of where current field starts. + /// + /// #### Returns + /// + /// the index of the end of field, or -1 if couldn't determine. int findEndText(String source, int ofs) { for (int i = ofs; i < source.length(); i++) { if (isAlpha(source.charAt(i)) == false && isNumeric(source.charAt(i)) == false) { @@ -950,30 +980,29 @@ int findEndText(String source, int ofs) { return -1; } - /** - * Test if a character is alpha (A-Z,a-z). - */ + /// Test if a character is alpha (A-Z,a-z). boolean isAlpha(char ch) { return ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z')); } - /** - * Test if a character is number (0-9). - */ + /// Test if a character is number (0-9). boolean isNumeric(char ch) { return (ch >= '0' && ch <= '9'); } - /** - * Parse the date pattern. - * - * The list will contain each token of the pattern. The first character of - * the token contains the pattern component type, or wildcard (*) for - * literal patterns. - * - * @param pattern - * @return parsed pattern. - */ + /// Parse the date pattern. + /// + /// The list will contain each token of the pattern. The first character of + /// the token contains the pattern component type, or wildcard (*) for + /// literal patterns. + /// + /// #### Parameters + /// + /// - `pattern` + /// + /// #### Returns + /// + /// parsed pattern. List parseDatePattern(String pattern) { List tokens = new Vector(); String tmp = null; diff --git a/Ports/CLDC11/src/java/util/AbstractCollection.java b/Ports/CLDC11/src/java/util/AbstractCollection.java index 658ffcdb1a..100913af1e 100644 --- a/Ports/CLDC11/src/java/util/AbstractCollection.java +++ b/Ports/CLDC11/src/java/util/AbstractCollection.java @@ -17,20 +17,16 @@ package java.util; -/** - * Class {@code AbstractCollection} is an abstract implementation of the {@code - * Collection} interface. A subclass must implement the abstract methods {@code - * iterator()} and {@code size()} to create an immutable collection. To create a - * modifiable collection it's necessary to override the {@code add()} method that - * currently throws an {@code UnsupportedOperationException}. - * - * @since 1.2 - */ +/// Class `AbstractCollection` is an abstract implementation of the `Collection` interface. A subclass must implement the abstract methods `iterator()` and `size()` to create an immutable collection. To create a +/// modifiable collection it's necessary to override the `add()` method that +/// currently throws an `UnsupportedOperationException`. +/// +/// #### Since +/// +/// 1.2 public abstract class AbstractCollection implements Collection { - /** - * Constructs a new instance of this AbstractCollection. - */ + /// Constructs a new instance of this AbstractCollection. protected AbstractCollection() { super(); } @@ -39,35 +35,40 @@ public boolean add(E object) { throw new UnsupportedOperationException(); } - /** - * Attempts to add all of the objects contained in {@code collection} - * to the contents of this {@code Collection} (optional). This implementation - * iterates over the given {@code Collection} and calls {@code add} for each - * element. If any of these calls return {@code true}, then {@code true} is - * returned as result of this method call, {@code false} otherwise. If this - * {@code Collection} does not support adding elements, an {@code - * UnsupportedOperationException} is thrown. - *

- * If the passed {@code Collection} is changed during the process of adding elements - * to this {@code Collection}, the behavior depends on the behavior of the passed - * {@code Collection}. - * - * @param collection - * the collection of objects. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if adding to this {@code Collection} is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this - * {@code Collection}. - * @throws IllegalArgumentException - * if an object cannot be added to this {@code Collection}. - * @throws NullPointerException - * if {@code collection} is {@code null}, or if it contains - * {@code null} elements and this {@code Collection} does not support - * such elements. - */ + /// Attempts to add all of the objects contained in `collection` + /// to the contents of this `Collection` (optional). This implementation + /// iterates over the given `Collection` and calls `add` for each + /// element. If any of these calls return `true`, then `true` is + /// returned as result of this method call, `false` otherwise. If this + /// `Collection` does not support adding elements, an `UnsupportedOperationException` is thrown. + /// + /// If the passed `Collection` is changed during the process of adding elements + /// to this `Collection`, the behavior depends on the behavior of the passed + /// `Collection`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of an object is inappropriate for this + /// `Collection`. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this `Collection`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` is `null`, or if it contains + /// `null` elements and this `Collection` does not support + /// such elements. public boolean addAll(Collection collection) { boolean result = false; Iterator it = collection.iterator(); @@ -79,22 +80,26 @@ public boolean addAll(Collection collection) { return result; } - /** - * Removes all elements from this {@code Collection}, leaving it empty (optional). - * This implementation iterates over this {@code Collection} and calls the {@code - * remove} method on each element. If the iterator does not support removal - * of elements, an {@code UnsupportedOperationException} is thrown. - *

- * Concrete implementations usually can clear a {@code Collection} more efficiently - * and should therefore overwrite this method. - * - * @throws UnsupportedOperationException - * it the iterator does not support removing elements from - * this {@code Collection} - * @see #iterator - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `Collection`, leaving it empty (optional). + /// This implementation iterates over this `Collection` and calls the `remove` method on each element. If the iterator does not support removal + /// of elements, an `UnsupportedOperationException` is thrown. + /// + /// Concrete implementations usually can clear a `Collection` more efficiently + /// and should therefore overwrite this method. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: @throws UnsupportedOperationException + /// it the iterator does not support removing elements from + /// this `Collection` + /// + /// #### See also + /// + /// - #iterator + /// + /// - #isEmpty + /// + /// - #size public void clear() { Iterator it = iterator(); while (it.hasNext()) { @@ -103,25 +108,29 @@ public void clear() { } } - /** - * Tests whether this {@code Collection} contains the specified object. This - * implementation iterates over this {@code Collection} and tests, whether any - * element is equal to the given object. If {@code object != null} then - * {@code object.equals(e)} is called for each element {@code e} returned by - * the iterator until the element is found. If {@code object == null} then - * each element {@code e} returned by the iterator is compared with the test - * {@code e == null}. - * - * @param object - * the object to search for. - * @return {@code true} if object is an element of this {@code Collection}, {@code - * false} otherwise. - * @throws ClassCastException - * if the object to look for isn't of the correct type. - * @throws NullPointerException - * if the object to look for is {@code null} and this - * {@code Collection} doesn't support {@code null} elements. - */ + /// Tests whether this `Collection` contains the specified object. This + /// implementation iterates over this `Collection` and tests, whether any + /// element is equal to the given object. If `object != null` then + /// `object.equals(e)` is called for each element `e` returned by + /// the iterator until the element is found. If `object == null` then + /// each element `e` returned by the iterator is compared with the test + /// `e == null`. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// `true` if object is an element of this `Collection`, `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the object to look for isn't of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the object to look for is `null` and this + /// `Collection` doesn't support `null` elements. public boolean contains(Object object) { Iterator it = iterator(); if (object != null) { @@ -140,26 +149,32 @@ public boolean contains(Object object) { return false; } - /** - * Tests whether this {@code Collection} contains all objects contained in the - * specified {@code Collection}. This implementation iterates over the specified - * {@code Collection}. If one element returned by the iterator is not contained in - * this {@code Collection}, then {@code false} is returned; {@code true} otherwise. - * - * @param collection - * the collection of objects. - * @return {@code true} if all objects in the specified {@code Collection} are - * elements of this {@code Collection}, {@code false} otherwise. - * @throws ClassCastException - * if one or more elements of {@code collection} isn't of the - * correct type. - * @throws NullPointerException - * if {@code collection} contains at least one {@code null} - * element and this {@code Collection} doesn't support {@code null} - * elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Tests whether this `Collection` contains all objects contained in the + /// specified `Collection`. This implementation iterates over the specified + /// `Collection`. If one element returned by the iterator is not contained in + /// this `Collection`, then `false` is returned; `true` otherwise. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if all objects in the specified `Collection` are + /// elements of this `Collection`, `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` isn't of the + /// correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one `null` + /// element and this `Collection` doesn't support `null` + /// elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean containsAll(Collection collection) { Iterator it = collection.iterator(); while (it.hasNext()) { @@ -170,56 +185,63 @@ public boolean containsAll(Collection collection) { return true; } - /** - * Returns if this {@code Collection} contains no elements. This implementation - * tests, whether {@code size} returns 0. - * - * @return {@code true} if this {@code Collection} has no elements, {@code false} - * otherwise. - * - * @see #size - */ + /// Returns if this `Collection` contains no elements. This implementation + /// tests, whether `size` returns 0. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size public boolean isEmpty() { return size() == 0; } - /** - * Returns an instance of {@link Iterator} that may be used to access the - * objects contained by this {@code Collection}. The order in which the elements are - * returned by the {@link Iterator} is not defined unless the instance of the - * {@code Collection} has a defined order. In that case, the elements are returned in that order. - *

- * In this class this method is declared abstract and has to be implemented - * by concrete {@code Collection} implementations. - * - * @return an iterator for accessing the {@code Collection} contents. - */ + /// Returns an instance of `Iterator` that may be used to access the + /// objects contained by this `Collection`. The order in which the elements are + /// returned by the `Iterator` is not defined unless the instance of the + /// `Collection` has a defined order. In that case, the elements are returned in that order. + /// + /// In this class this method is declared abstract and has to be implemented + /// by concrete `Collection` implementations. + /// + /// #### Returns + /// + /// an iterator for accessing the `Collection` contents. public abstract Iterator iterator(); - /** - * Removes one instance of the specified object from this {@code Collection} if one - * is contained (optional). This implementation iterates over this - * {@code Collection} and tests for each element {@code e} returned by the iterator, - * whether {@code e} is equal to the given object. If {@code object != null} - * then this test is performed using {@code object.equals(e)}, otherwise - * using {@code object == null}. If an element equal to the given object is - * found, then the {@code remove} method is called on the iterator and - * {@code true} is returned, {@code false} otherwise. If the iterator does - * not support removing elements, an {@code UnsupportedOperationException} - * is thrown. - * - * @param object - * the object to remove. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if the object passed is not of the correct type. - * @throws NullPointerException - * if {@code object} is {@code null} and this {@code Collection} - * doesn't support {@code null} elements. - */ + /// Removes one instance of the specified object from this `Collection` if one + /// is contained (optional). This implementation iterates over this + /// `Collection` and tests for each element `e` returned by the iterator, + /// whether `e` is equal to the given object. If `object != null` + /// then this test is performed using `object.equals(e)`, otherwise + /// using `object == null`. If an element equal to the given object is + /// found, then the `remove` method is called on the iterator and + /// `true` is returned, `false` otherwise. If the iterator does + /// not support removing elements, an `UnsupportedOperationException` + /// is thrown. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: if the object passed is not of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `object` is `null` and this `Collection` + /// doesn't support `null` elements. public boolean remove(Object object) { Iterator it = iterator(); if (object != null) { @@ -240,35 +262,40 @@ public boolean remove(Object object) { return false; } - /** - * Removes all occurrences in this {@code Collection} of each object in the - * specified {@code Collection} (optional). After this method returns none of the - * elements in the passed {@code Collection} can be found in this {@code Collection} - * anymore. - *

- * This implementation iterates over this {@code Collection} and tests for each - * element {@code e} returned by the iterator, whether it is contained in - * the specified {@code Collection}. If this test is positive, then the {@code - * remove} method is called on the iterator. If the iterator does not - * support removing elements, an {@code UnsupportedOperationException} is - * thrown. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if one or more elements of {@code collection} isn't of the - * correct type. - * @throws NullPointerException - * if {@code collection} contains at least one {@code null} - * element and this {@code Collection} doesn't support {@code null} - * elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Removes all occurrences in this `Collection` of each object in the + /// specified `Collection` (optional). After this method returns none of the + /// elements in the passed `Collection` can be found in this `Collection` + /// anymore. + /// + /// This implementation iterates over this `Collection` and tests for each + /// element `e` returned by the iterator, whether it is contained in + /// the specified `Collection`. If this test is positive, then the `remove` method is called on the iterator. If the iterator does not + /// support removing elements, an `UnsupportedOperationException` is + /// thrown. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` isn't of the + /// correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one `null` + /// element and this `Collection` doesn't support `null` + /// elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean removeAll(Collection collection) { boolean result = false; Iterator it = iterator(); @@ -281,35 +308,40 @@ public boolean removeAll(Collection collection) { return result; } - /** - * Removes all objects from this {@code Collection} that are not also found in the - * {@code Collection} passed (optional). After this method returns this {@code Collection} - * will only contain elements that also can be found in the {@code Collection} - * passed to this method. - *

- * This implementation iterates over this {@code Collection} and tests for each - * element {@code e} returned by the iterator, whether it is contained in - * the specified {@code Collection}. If this test is negative, then the {@code - * remove} method is called on the iterator. If the iterator does not - * support removing elements, an {@code UnsupportedOperationException} is - * thrown. - * - * @param collection - * the collection of objects to retain. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if one or more elements of {@code collection} - * isn't of the correct type. - * @throws NullPointerException - * if {@code collection} contains at least one - * {@code null} element and this {@code Collection} doesn't support - * {@code null} elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Removes all objects from this `Collection` that are not also found in the + /// `Collection` passed (optional). After this method returns this `Collection` + /// will only contain elements that also can be found in the `Collection` + /// passed to this method. + /// + /// This implementation iterates over this `Collection` and tests for each + /// element `e` returned by the iterator, whether it is contained in + /// the specified `Collection`. If this test is negative, then the `remove` method is called on the iterator. If the iterator does not + /// support removing elements, an `UnsupportedOperationException` is + /// thrown. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to retain. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` + /// isn't of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one + /// `null` element and this `Collection` doesn't support + /// `null` elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean retainAll(Collection collection) { boolean result = false; Iterator it = iterator(); @@ -322,25 +354,25 @@ public boolean retainAll(Collection collection) { return result; } - /** - * Returns a count of how many objects this {@code Collection} contains. - *

- * In this class this method is declared abstract and has to be implemented - * by concrete {@code Collection} implementations. - * - * @return how many objects this {@code Collection} contains, or {@code Integer.MAX_VALUE} - * if there are more than {@code Integer.MAX_VALUE} elements in this - * {@code Collection}. - */ + /// Returns a count of how many objects this `Collection` contains. + /// + /// In this class this method is declared abstract and has to be implemented + /// by concrete `Collection` implementations. + /// + /// #### Returns + /// + /// @return how many objects this `Collection` contains, or `Integer.MAX_VALUE` + /// if there are more than `Integer.MAX_VALUE` elements in this + /// `Collection`. public abstract int size(); - /** - * Returns the string representation of this {@code Collection}. The presentation - * has a specific format. It is enclosed by square brackets ("[]"). Elements - * are separated by ', ' (comma and space). - * - * @return the string representation of this {@code Collection}. - */ + /// Returns the string representation of this `Collection`. The presentation + /// has a specific format. It is enclosed by square brackets ("[]"). Elements + /// are separated by ', ' (comma and space). + /// + /// #### Returns + /// + /// the string representation of this `Collection`. @Override public String toString() { if (isEmpty()) { @@ -366,32 +398,37 @@ public String toString() { } - /** - * Returns a new array containing all elements contained in this - * {@code ArrayList}. - * - * @return an array of the elements from this {@code ArrayList} - */ + /// Returns a new array containing all elements contained in this + /// `ArrayList`. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList` @Override public Object[] toArray() { return ArrayList.toObjectArray(this); } - /** - * Returns an array containing all elements contained in this - * {@code ArrayList}. If the specified array is large enough to hold the - * elements, the specified array is used, otherwise an array of the same - * type is created. If the specified array is used and is larger than this - * {@code ArrayList}, the array element following the collection elements - * is set to null. - * - * @param contents - * the array. - * @return an array of the elements from this {@code ArrayList}. - * @throws ArrayStoreException - * when the type of an element in this {@code ArrayList} cannot - * be stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this + /// `ArrayList`. If the specified array is large enough to hold the + /// elements, the specified array is used, otherwise an array of the same + /// type is created. If the specified array is used and is larger than this + /// `ArrayList`, the array element following the collection elements + /// is set to null. + /// + /// #### Parameters + /// + /// - `contents`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// when the type of an element in this `ArrayList` cannot + /// be stored in the type of the specified array. @Override @SuppressWarnings("unchecked") public T[] toArray(T[] contents) { diff --git a/Ports/CLDC11/src/java/util/AbstractList.java b/Ports/CLDC11/src/java/util/AbstractList.java index a398147ad0..f20812d46a 100644 --- a/Ports/CLDC11/src/java/util/AbstractList.java +++ b/Ports/CLDC11/src/java/util/AbstractList.java @@ -18,22 +18,20 @@ package java.util; -/** - * {@code AbstractList} is an abstract implementation of the {@code List} interface, optimized - * for a backing store which supports random access. This implementation does - * not support adding or replacing. A subclass must implement the abstract - * methods {@code get()} and {@code size()}, and to create a - * modifiable {@code List} it's necessary to override the {@code add()} method that - * currently throws an {@code UnsupportedOperationException}. - * - * @since 1.2 - */ +/// `AbstractList` is an abstract implementation of the `List` interface, optimized +/// for a backing store which supports random access. This implementation does +/// not support adding or replacing. A subclass must implement the abstract +/// methods `get()` and `size()`, and to create a +/// modifiable `List` it's necessary to override the `add()` method that +/// currently throws an `UnsupportedOperationException`. +/// +/// #### Since +/// +/// 1.2 public abstract class AbstractList extends AbstractCollection implements List { - /** - * A counter for changes to the list. - */ + /// A counter for changes to the list. protected transient int modCount; private class SimpleListIterator implements Iterator { @@ -369,82 +367,88 @@ void sizeChanged(boolean increment) { } } - /** - * Constructs a new instance of this AbstractList. - */ + /// Constructs a new instance of this AbstractList. protected AbstractList() { super(); } - /** - * Inserts the specified object into this List at the specified location. - * The object is inserted before any previous element at the specified - * location. If the location is equal to the size of this List, the object - * is added at the end. - *

- * Concrete implementations that would like to support the add functionality - * must override this method. - * - * @param location - * the index at which to insert. - * @param object - * the object to add. - * - * @throws UnsupportedOperationException - * if adding to this List is not supported. - * @throws ClassCastException - * if the class of the object is inappropriate for this - * List - * @throws IllegalArgumentException - * if the object cannot be added to this List - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Inserts the specified object into this List at the specified location. + /// The object is inserted before any previous element at the specified + /// location. If the location is equal to the size of this List, the object + /// is added at the end. + /// + /// Concrete implementations that would like to support the add functionality + /// must override this method. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `object`: the object to add. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this List is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the object is inappropriate for this + /// List + /// + /// - `IllegalArgumentException`: if the object cannot be added to this List + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public void add(int location, E object) { throw new UnsupportedOperationException(); } - /** - * Adds the specified object at the end of this List. - * - * - * @param object - * the object to add - * @return true - * - * @throws UnsupportedOperationException - * if adding to this List is not supported - * @throws ClassCastException - * if the class of the object is inappropriate for this - * List - * @throws IllegalArgumentException - * if the object cannot be added to this List - */ + /// Adds the specified object at the end of this List. + /// + /// #### Parameters + /// + /// - `object`: the object to add + /// + /// #### Returns + /// + /// true + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this List is not supported + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the object is inappropriate for this + /// List + /// + /// - `IllegalArgumentException`: if the object cannot be added to this List @Override public boolean add(E object) { add(size(), object); return true; } - /** - * Inserts the objects in the specified Collection at the specified location - * in this List. The objects are added in the order they are returned from - * the collection's iterator. - * - * @param location - * the index at which to insert. - * @param collection - * the Collection of objects - * @return {@code true} if this List is modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * if adding to this list is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this list. - * @throws IllegalArgumentException - * if an object cannot be added to this list. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || > size()} - */ + /// Inserts the objects in the specified Collection at the specified location + /// in this List. The objects are added in the order they are returned from + /// the collection's iterator. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `collection`: the Collection of objects + /// + /// #### Returns + /// + /// `true` if this List is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this list is not supported. + /// + /// - `ClassCastException`: if the class of an object is inappropriate for this list. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this list. + /// + /// - `IndexOutOfBoundsException`: if `location size()` public boolean addAll(int location, Collection collection) { Iterator it = collection.iterator(); while (it.hasNext()) { @@ -453,30 +457,38 @@ public boolean addAll(int location, Collection collection) { return !collection.isEmpty(); } - /** - * Removes all elements from this list, leaving it empty. - * - * @throws UnsupportedOperationException - * if removing from this list is not supported. - * @see List#isEmpty - * @see List#size - */ + /// Removes all elements from this list, leaving it empty. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this list is not supported. + /// + /// #### See also + /// + /// - List#isEmpty + /// + /// - List#size @Override public void clear() { removeRange(0, size()); } - /** - * Compares the specified object to this list and return true if they are - * equal. Two lists are equal when they both contain the same objects in the - * same order. - * - * @param object - * the object to compare to this object. - * @return {@code true} if the specified object is equal to this list, - * {@code false} otherwise. - * @see #hashCode - */ + /// Compares the specified object to this list and return true if they are + /// equal. Two lists are equal when they both contain the same objects in the + /// same order. + /// + /// #### Parameters + /// + /// - `object`: the object to compare to this object. + /// + /// #### Returns + /// + /// @return `true` if the specified object is equal to this list, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #hashCode @Override public boolean equals(Object object) { if (this == object) { @@ -500,25 +512,33 @@ public boolean equals(Object object) { return false; } - /** - * Returns the element at the specified location in this list. - * - * @param location - * the index of the element to return. - * @return the element at the specified index. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Returns the element at the specified location in this list. + /// + /// #### Parameters + /// + /// - `location`: the index of the element to return. + /// + /// #### Returns + /// + /// the element at the specified index. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public abstract E get(int location); - /** - * Returns the hash code of this list. The hash code is calculated by taking - * each element's hashcode into account. - * - * @return the hash code. - * @see #equals - * @see List#hashCode() - */ + /// Returns the hash code of this list. The hash code is calculated by taking + /// each element's hashcode into account. + /// + /// #### Returns + /// + /// the hash code. + /// + /// #### See also + /// + /// - #equals + /// + /// - List#hashCode() @Override public int hashCode() { int result = 1; @@ -530,15 +550,17 @@ public int hashCode() { return result; } - /** - * Searches this list for the specified object and returns the index of the - * first occurrence. - * - * @param object - * the object to search for. - * @return the index of the first occurrence of the object, or -1 if it was - * not found. - */ + /// Searches this list for the specified object and returns the index of the + /// first occurrence. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return the index of the first occurrence of the object, or -1 if it was + /// not found. public int indexOf(Object object) { ListIterator it = listIterator(); if (object != null) { @@ -557,27 +579,32 @@ public int indexOf(Object object) { return -1; } - /** - * Returns an iterator on the elements of this list. The elements are - * iterated in the same order as they occur in the list. - * - * @return an iterator on the elements of this list. - * @see Iterator - */ + /// Returns an iterator on the elements of this list. The elements are + /// iterated in the same order as they occur in the list. + /// + /// #### Returns + /// + /// an iterator on the elements of this list. + /// + /// #### See also + /// + /// - Iterator @Override public Iterator iterator() { return new SimpleListIterator(); } - /** - * Searches this list for the specified object and returns the index of the - * last occurrence. - * - * @param object - * the object to search for. - * @return the index of the last occurrence of the object, or -1 if the - * object was not found. - */ + /// Searches this list for the specified object and returns the index of the + /// last occurrence. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return the index of the last occurrence of the object, or -1 if the + /// object was not found. public int lastIndexOf(Object object) { ListIterator it = listIterator(size()); if (object != null) { @@ -596,61 +623,76 @@ public int lastIndexOf(Object object) { return -1; } - /** - * Returns a ListIterator on the elements of this list. The elements are - * iterated in the same order that they occur in the list. - * - * @return a ListIterator on the elements of this list - * @see ListIterator - */ + /// Returns a ListIterator on the elements of this list. The elements are + /// iterated in the same order that they occur in the list. + /// + /// #### Returns + /// + /// a ListIterator on the elements of this list + /// + /// #### See also + /// + /// - ListIterator public ListIterator listIterator() { return listIterator(0); } - /** - * Returns a list iterator on the elements of this list. The elements are - * iterated in the same order as they occur in the list. The iteration - * starts at the specified location. - * - * @param location - * the index at which to start the iteration. - * @return a ListIterator on the elements of this list. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || location > size()} - * @see ListIterator - */ + /// Returns a list iterator on the elements of this list. The elements are + /// iterated in the same order as they occur in the list. The iteration + /// starts at the specified location. + /// + /// #### Parameters + /// + /// - `location`: the index at which to start the iteration. + /// + /// #### Returns + /// + /// a ListIterator on the elements of this list. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location size()` + /// + /// #### See also + /// + /// - ListIterator public ListIterator listIterator(int location) { return new FullListIterator(location); } - /** - * Removes the object at the specified location from this list. - * - * @param location - * the index of the object to remove. - * @return the removed object. - * @throws UnsupportedOperationException - * if removing from this list is not supported. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Removes the object at the specified location from this list. + /// + /// #### Parameters + /// + /// - `location`: the index of the object to remove. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this list is not supported. + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public E remove(int location) { throw new UnsupportedOperationException(); } - /** - * Removes the objects in the specified range from the start to the end - * index minus one. - * - * @param start - * the index at which to start removing. - * @param end - * the index after the last element to remove. - * @throws UnsupportedOperationException - * if removing from this list is not supported. - * @throws IndexOutOfBoundsException - * if {@code start < 0} or {@code start >= size()}. - */ + /// Removes the objects in the specified range from the start to the end + /// index minus one. + /// + /// #### Parameters + /// + /// - `start`: the index at which to start removing. + /// + /// - `end`: the index after the last element to remove. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this list is not supported. + /// + /// - `IndexOutOfBoundsException`: if `start = size()`. protected void removeRange(int start, int end) { Iterator it = listIterator(start); for (int i = start; i < end; i++) { @@ -659,72 +701,80 @@ protected void removeRange(int start, int end) { } } - /** - * Replaces the element at the specified location in this list with the - * specified object. - * - * @param location - * the index at which to put the specified object. - * @param object - * the object to add. - * @return the previous element at the index. - * @throws UnsupportedOperationException - * if replacing elements in this list is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this list. - * @throws IllegalArgumentException - * if an object cannot be added to this list. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Replaces the element at the specified location in this list with the + /// specified object. + /// + /// #### Parameters + /// + /// - `location`: the index at which to put the specified object. + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// the previous element at the index. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if replacing elements in this list is not supported. + /// + /// - `ClassCastException`: if the class of an object is inappropriate for this list. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this list. + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public E set(int location, E object) { throw new UnsupportedOperationException(); } - /** - * Returns a part of consecutive elements of this list as a view. The - * returned view will be of zero length if start equals end. Any change that - * occurs in the returned subList will be reflected to the original list, - * and vice-versa. All the supported optional operations by the original - * list will also be supported by this subList. - *

- * This method can be used as a handy method to do some operations on a sub - * range of the original list, for example - * {@code list.subList(from, to).clear();} - *

- * If the original list is modified in other ways than through the returned - * subList, the behavior of the returned subList becomes undefined. - *

- * The returned subList is a subclass of AbstractList. The subclass stores - * offset, size of itself, and modCount of the original list. If the - * original list implements RandomAccess interface, the returned subList - * also implements RandomAccess interface. - *

- * The subList's set(int, Object), get(int), add(int, Object), remove(int), - * addAll(int, Collection) and removeRange(int, int) methods first check the - * bounds, adjust offsets and then call the corresponding methods of the - * original AbstractList. addAll(Collection c) method of the returned - * subList calls the original addAll(offset + size, c). - *

- * The listIterator(int) method of the subList wraps the original list - * iterator. The iterator() method of the subList invokes the original - * listIterator() method, and the size() method merely returns the size of - * the subList. - *

- * All methods will throw a ConcurrentModificationException if the modCount - * of the original list is not equal to the expected value. - * - * @param start - * start index of the subList (inclusive). - * @param end - * end index of the subList, (exclusive). - * @return a subList view of this list starting from {@code start} - * (inclusive), and ending with {@code end} (exclusive) - * @throws IndexOutOfBoundsException - * if (start < 0 || end > size()) - * @throws IllegalArgumentException - * if (start > end) - */ + /// Returns a part of consecutive elements of this list as a view. The + /// returned view will be of zero length if start equals end. Any change that + /// occurs in the returned subList will be reflected to the original list, + /// and vice-versa. All the supported optional operations by the original + /// list will also be supported by this subList. + /// + /// This method can be used as a handy method to do some operations on a sub + /// range of the original list, for example + /// `list.subList(from, to).clear();` + /// + /// If the original list is modified in other ways than through the returned + /// subList, the behavior of the returned subList becomes undefined. + /// + /// The returned subList is a subclass of AbstractList. The subclass stores + /// offset, size of itself, and modCount of the original list. If the + /// original list implements RandomAccess interface, the returned subList + /// also implements RandomAccess interface. + /// + /// The subList's set(int, Object), get(int), add(int, Object), remove(int), + /// addAll(int, Collection) and removeRange(int, int) methods first check the + /// bounds, adjust offsets and then call the corresponding methods of the + /// original AbstractList. addAll(Collection c) method of the returned + /// subList calls the original addAll(offset + size, c). + /// + /// The listIterator(int) method of the subList wraps the original list + /// iterator. The iterator() method of the subList invokes the original + /// listIterator() method, and the size() method merely returns the size of + /// the subList. + /// + /// All methods will throw a ConcurrentModificationException if the modCount + /// of the original list is not equal to the expected value. + /// + /// #### Parameters + /// + /// - `start`: start index of the subList (inclusive). + /// + /// - `end`: end index of the subList, (exclusive). + /// + /// #### Returns + /// + /// @return a subList view of this list starting from `start` + /// (inclusive), and ending with `end` (exclusive) + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if (start size()) + /// + /// - `IllegalArgumentException`: if (start > end) public List subList(int start, int end) { if (0 <= start && end <= size()) { if (start <= end) { @@ -738,12 +788,12 @@ public List subList(int start, int end) { throw new IndexOutOfBoundsException(); } - /** - * Returns a new array containing all elements contained in this - * {@code ArrayList}. - * - * @return an array of the elements from this {@code ArrayList} - */ + /// Returns a new array containing all elements contained in this + /// `ArrayList`. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList` @Override public Object[] toArray() { Object[] result = new Object[size()]; @@ -753,21 +803,26 @@ public Object[] toArray() { return result; } - /** - * Returns an array containing all elements contained in this - * {@code ArrayList}. If the specified array is large enough to hold the - * elements, the specified array is used, otherwise an array of the same - * type is created. If the specified array is used and is larger than this - * {@code ArrayList}, the array element following the collection elements - * is set to null. - * - * @param contents - * the array. - * @return an array of the elements from this {@code ArrayList}. - * @throws ArrayStoreException - * when the type of an element in this {@code ArrayList} cannot - * be stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this + /// `ArrayList`. If the specified array is large enough to hold the + /// elements, the specified array is used, otherwise an array of the same + /// type is created. If the specified array is used and is larger than this + /// `ArrayList`, the array element following the collection elements + /// is set to null. + /// + /// #### Parameters + /// + /// - `contents`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// when the type of an element in this `ArrayList` cannot + /// be stored in the type of the specified array. @Override @SuppressWarnings("unchecked") public T[] toArray(T[] contents) { diff --git a/Ports/CLDC11/src/java/util/AbstractMap.java b/Ports/CLDC11/src/java/util/AbstractMap.java index 3d57ad8c43..4f0fe8840f 100644 --- a/Ports/CLDC11/src/java/util/AbstractMap.java +++ b/Ports/CLDC11/src/java/util/AbstractMap.java @@ -18,13 +18,13 @@ package java.util; -/** - * This class is an abstract implementation of the {@code Map} interface. This - * implementation does not support adding. A subclass must implement the - * abstract method entrySet(). - * - * @since 1.2 - */ +/// This class is an abstract implementation of the `Map` interface. This +/// implementation does not support adding. A subclass must implement the +/// abstract method entrySet(). +/// +/// #### Since +/// +/// 1.2 public abstract class AbstractMap implements Map { // Lazily initialized key set. @@ -32,16 +32,16 @@ public abstract class AbstractMap implements Map { Collection valuesCollection; - /** - * An immutable key-value mapping. - * - * @param - * the type of key - * @param - * the type of value - * - * @since 1.6 - */ + /// An immutable key-value mapping. + /// + /// @param + /// the type of key + /// @param + /// the type of value + /// + /// #### Since + /// + /// 1.6 public static class SimpleImmutableEntry implements Map.Entry { private static final long serialVersionUID = 7138329143949025153L; @@ -50,70 +50,74 @@ public static class SimpleImmutableEntry implements Map.Entry { private V value; - /** - * Constructs a new instance by key and value. - * - * @param theKey - * the key - * @param theValue - * the value - */ + /// Constructs a new instance by key and value. + /// + /// #### Parameters + /// + /// - `theKey`: the key + /// + /// - `theValue`: the value public SimpleImmutableEntry(K theKey, V theValue) { key = theKey; value = theValue; } - /** - * Constructs a new instance by an entry - * - * @param entry - * the entry - */ + /// Constructs a new instance by an entry + /// + /// #### Parameters + /// + /// - `entry`: the entry public SimpleImmutableEntry(Map.Entry entry) { key = entry.getKey(); value = entry.getValue(); } - /** - * {@inheritDoc} - * - * @see java.util.Map.Entry#getKey() - */ + /// {@inheritDoc} + /// + /// #### See also + /// + /// - java.util.Map.Entry#getKey() public K getKey() { return key; } - /** - * {@inheritDoc} - * - * @see java.util.Map.Entry#getValue() - */ + /// {@inheritDoc} + /// + /// #### See also + /// + /// - java.util.Map.Entry#getValue() public V getValue() { return value; } - /** - * Throws an UnsupportedOperationException. - * - * @param object - * new value - * @return (Does not) - * @throws UnsupportedOperationException - * always - * - * @see java.util.Map.Entry#setValue(java.lang.Object) - */ + /// Throws an UnsupportedOperationException. + /// + /// #### Parameters + /// + /// - `object`: new value + /// + /// #### Returns + /// + /// (Does not) + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: always + /// + /// #### See also + /// + /// - java.util.Map.Entry#setValue(java.lang.Object) public V setValue(@SuppressWarnings("unused") V object) { throw new UnsupportedOperationException(); } - /** - * Answers whether the object is equal to this entry. This works across - * all kinds of the Map.Entry interface. - * - * @see java.lang.Object#equals(java.lang.Object) - */ + /// Answers whether the object is equal to this entry. This works across + /// all kinds of the Map.Entry interface. + /// + /// #### See also + /// + /// - java.lang.Object#equals(java.lang.Object) @Override public boolean equals(Object object) { if (this == object) { @@ -129,38 +133,38 @@ public boolean equals(Object object) { return false; } - /** - * Answers the hash code of this entry. - * - * @see java.lang.Object#hashCode() - */ + /// Answers the hash code of this entry. + /// + /// #### See also + /// + /// - java.lang.Object#hashCode() @Override public int hashCode() { return (key == null ? 0 : key.hashCode()) ^ (value == null ? 0 : value.hashCode()); } - /** - * Answers a String representation of this entry. - * - * @see java.lang.Object#toString() - */ + /// Answers a String representation of this entry. + /// + /// #### See also + /// + /// - java.lang.Object#toString() @Override public String toString() { return key + "=" + value; //$NON-NLS-1$ } } - /** - * A key-value mapping. - * - * @param - * the type of key - * @param - * the type of value - * - * @since 1.6 - */ + /// A key-value mapping. + /// + /// @param + /// the type of key + /// @param + /// the type of value + /// + /// #### Since + /// + /// 1.6 public static class SimpleEntry implements Map.Entry { private static final long serialVersionUID = -8499721149061103585L; @@ -169,65 +173,63 @@ public static class SimpleEntry implements Map.Entry { private V value; - /** - * Constructs a new instance by key and value. - * - * @param theKey - * the key - * @param theValue - * the value - */ + /// Constructs a new instance by key and value. + /// + /// #### Parameters + /// + /// - `theKey`: the key + /// + /// - `theValue`: the value public SimpleEntry(K theKey, V theValue) { key = theKey; value = theValue; } - /** - * Constructs a new instance by an entry - * - * @param entry - * the entry - */ + /// Constructs a new instance by an entry + /// + /// #### Parameters + /// + /// - `entry`: the entry public SimpleEntry(Map.Entry entry) { key = entry.getKey(); value = entry.getValue(); } - /** - * {@inheritDoc} - * - * @see java.util.Map.Entry#getKey() - */ + /// {@inheritDoc} + /// + /// #### See also + /// + /// - java.util.Map.Entry#getKey() public K getKey() { return key; } - /** - * {@inheritDoc} - * - * @see java.util.Map.Entry#getValue() - */ + /// {@inheritDoc} + /// + /// #### See also + /// + /// - java.util.Map.Entry#getValue() public V getValue() { return value; } - /** - * {@inheritDoc} - * - * @see java.util.Map.Entry#setValue(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### See also + /// + /// - java.util.Map.Entry#setValue(java.lang.Object) public V setValue(V object) { V result = value; value = object; return result; } - /** - * Answers whether the object is equal to this entry. This works across - * all kinds of the Map.Entry interface. - * - * @see java.lang.Object#equals(java.lang.Object) - */ + /// Answers whether the object is equal to this entry. This works across + /// all kinds of the Map.Entry interface. + /// + /// #### See also + /// + /// - java.lang.Object#equals(java.lang.Object) @Override public boolean equals(Object object) { if (this == object) { @@ -243,55 +245,58 @@ public boolean equals(Object object) { return false; } - /** - * Answers the hash code of this entry. - * - * @see java.lang.Object#hashCode() - */ + /// Answers the hash code of this entry. + /// + /// #### See also + /// + /// - java.lang.Object#hashCode() @Override public int hashCode() { return (key == null ? 0 : key.hashCode()) ^ (value == null ? 0 : value.hashCode()); } - /** - * Answers a String representation of this entry. - * - * @see java.lang.Object#toString() - */ + /// Answers a String representation of this entry. + /// + /// #### See also + /// + /// - java.lang.Object#toString() @Override public String toString() { return key + "=" + value; //$NON-NLS-1$ } } - /** - * Constructs a new instance of this {@code AbstractMap}. - */ + /// Constructs a new instance of this `AbstractMap`. protected AbstractMap() { super(); } - /** - * Removes all elements from this map, leaving it empty. - * - * @throws UnsupportedOperationException - * if removing from this map is not supported. - * @see #isEmpty() - * @see #size() - */ + /// Removes all elements from this map, leaving it empty. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this map is not supported. + /// + /// #### See also + /// + /// - #isEmpty() + /// + /// - #size() public void clear() { entrySet().clear(); } - /** - * Returns whether this map contains the specified key. - * - * @param key - * the key to search for. - * @return {@code true} if this map contains the specified key, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified key, + /// `false` otherwise. public boolean containsKey(Object key) { Iterator> it = entrySet().iterator(); if (key != null) { @@ -310,14 +315,16 @@ public boolean containsKey(Object key) { return false; } - /** - * Returns whether this map contains the specified value. - * - * @param value - * the value to search for. - * @return {@code true} if this map contains the specified value, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified value. + /// + /// #### Parameters + /// + /// - `value`: the value to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified value, + /// `false` otherwise. public boolean containsValue(Object value) { Iterator> it = entrySet().iterator(); if (value != null) { @@ -336,26 +343,32 @@ public boolean containsValue(Object value) { return false; } - /** - * Returns a set containing all of the mappings in this map. Each mapping is - * an instance of {@link Map.Entry}. As the set is backed by this map, - * changes in one will be reflected in the other. - * - * @return a set of the mappings. - */ + /// Returns a set containing all of the mappings in this map. Each mapping is + /// an instance of `Map.Entry`. As the set is backed by this map, + /// changes in one will be reflected in the other. + /// + /// #### Returns + /// + /// a set of the mappings. public abstract Set> entrySet(); - /** - * Compares the specified object to this instance, and returns {@code true} - * if the specified object is a map and both maps contain the same mappings. - * - * @param object - * the object to compare with this object. - * @return boolean {@code true} if the object is the same as this object, - * and {@code false} if it is different from this object. - * @see #hashCode() - * @see #entrySet() - */ + /// Compares the specified object to this instance, and returns `true` + /// if the specified object is a map and both maps contain the same mappings. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object. + /// + /// #### Returns + /// + /// @return boolean `true` if the object is the same as this object, + /// and `false` if it is different from this object. + /// + /// #### See also + /// + /// - #hashCode() + /// + /// - #entrySet() @Override public boolean equals(Object object) { if (this == object) { @@ -392,14 +405,16 @@ public boolean equals(Object object) { return false; } - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key, or {@code null} - * if no mapping for the specified key is found. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// @return the value of the mapping with the specified key, or `null` + /// if no mapping for the specified key is found. public V get(Object key) { Iterator> it = entrySet().iterator(); if (key != null) { @@ -420,13 +435,16 @@ public V get(Object key) { return null; } - /** - * Returns the hash code for this object. Objects which are equal must - * return the same value for this method. - * - * @return the hash code of this object. - * @see #equals(Object) - */ + /// Returns the hash code for this object. Objects which are equal must + /// return the same value for this method. + /// + /// #### Returns + /// + /// the hash code of this object. + /// + /// #### See also + /// + /// - #equals(Object) @Override public int hashCode() { int result = 0; @@ -437,24 +455,27 @@ public int hashCode() { return result; } - /** - * Returns whether this map is empty. - * - * @return {@code true} if this map has no elements, {@code false} - * otherwise. - * @see #size() - */ + /// Returns whether this map is empty. + /// + /// #### Returns + /// + /// @return `true` if this map has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size() public boolean isEmpty() { return size() == 0; } - /** - * Returns a set of the keys contained in this map. The set is backed by - * this map so changes to one are reflected by the other. The returned set - * does not support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this map. The set is backed by + /// this map so changes to one are reflected by the other. The returned set + /// does not support adding. + /// + /// #### Returns + /// + /// a set of the keys. public Set keySet() { if (keySet == null) { keySet = new AbstractSet() { @@ -492,48 +513,57 @@ public void remove() { return keySet; } - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no mapping. - * @throws UnsupportedOperationException - * if adding to this map is not supported. - * @throws ClassCastException - * if the class of the key or value is inappropriate for this - * map. - * @throws IllegalArgumentException - * if the key or value cannot be added to this map. - * @throws NullPointerException - * if the key or value is {@code null} and this Map does not - * support {@code null} keys or values. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no mapping. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this map is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the key or value is inappropriate for this + /// map. + /// + /// - `IllegalArgumentException`: if the key or value cannot be added to this map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the key or value is `null` and this Map does not + /// support `null` keys or values. public V put(@SuppressWarnings("unused") K key, @SuppressWarnings("unused") V value) { throw new UnsupportedOperationException(); } - /** - * Copies every mapping in the specified map to this map. - * - * @param map - * the map to copy mappings from. - * @throws UnsupportedOperationException - * if adding to this map is not supported. - * @throws ClassCastException - * if the class of a key or value is inappropriate for this - * map. - * @throws IllegalArgumentException - * if a key or value cannot be added to this map. - * @throws NullPointerException - * if a key or value is {@code null} and this map does not - * support {@code null} keys or values. - */ + /// Copies every mapping in the specified map to this map. + /// + /// #### Parameters + /// + /// - `map`: the map to copy mappings from. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this map is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of a key or value is inappropriate for this + /// map. + /// + /// - `IllegalArgumentException`: if a key or value cannot be added to this map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if a key or value is `null` and this map does not + /// support `null` keys or values. public void putAll(Map map) { Iterator it = map.entrySet().iterator(); while (it.hasNext()) { @@ -542,16 +572,20 @@ public void putAll(Map map) { } } - /** - * Removes a mapping with the specified key from this Map. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping or {@code null} if no mapping - * for the specified key was found. - * @throws UnsupportedOperationException - * if removing from this map is not supported. - */ + /// Removes a mapping with the specified key from this Map. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping or `null` if no mapping + /// for the specified key was found. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this map is not supported. public V remove(Object key) { Iterator> it = entrySet().iterator(); if (key != null) { @@ -574,20 +608,20 @@ public V remove(Object key) { return null; } - /** - * Returns the number of elements in this map. - * - * @return the number of elements in this map. - */ + /// Returns the number of elements in this map. + /// + /// #### Returns + /// + /// the number of elements in this map. public int size() { return entrySet().size(); } - /** - * Returns the string representation of this map. - * - * @return the string representation of this map. - */ + /// Returns the string representation of this map. + /// + /// #### Returns + /// + /// the string representation of this map. @Override public String toString() { if (isEmpty()) { @@ -620,25 +654,25 @@ public String toString() { return buffer.toString(); } - /** - * Returns a collection of the values contained in this map. The collection - * is backed by this map so changes to one are reflected by the other. The - * collection supports remove, removeAll, retainAll and clear operations, - * and it does not support add or addAll operations. - *

- * This method returns a collection which is the subclass of - * AbstractCollection. The iterator method of this subclass returns a - * "wrapper object" over the iterator of map's entrySet(). The {@code size} - * method wraps the map's size method and the {@code contains} method wraps - * the map's containsValue method. - *

- * The collection is created when this method is called for the first time - * and returned in response to all subsequent calls. This method may return - * different collections when multiple concurrent calls occur to this - * method, since no synchronization is performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a collection of the values contained in this map. The collection + /// is backed by this map so changes to one are reflected by the other. The + /// collection supports remove, removeAll, retainAll and clear operations, + /// and it does not support add or addAll operations. + /// + /// This method returns a collection which is the subclass of + /// AbstractCollection. The iterator method of this subclass returns a + /// "wrapper object" over the iterator of map's entrySet(). The `size` + /// method wraps the map's size method and the `contains` method wraps + /// the map's containsValue method. + /// + /// The collection is created when this method is called for the first time + /// and returned in response to all subsequent calls. This method may return + /// different collections when multiple concurrent calls occur to this + /// method, since no synchronization is performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. public Collection values() { if (valuesCollection == null) { valuesCollection = new AbstractCollection() { diff --git a/Ports/CLDC11/src/java/util/AbstractQueue.java b/Ports/CLDC11/src/java/util/AbstractQueue.java index 4b4fccf797..3f8362d87c 100644 --- a/Ports/CLDC11/src/java/util/AbstractQueue.java +++ b/Ports/CLDC11/src/java/util/AbstractQueue.java @@ -16,35 +16,35 @@ package java.util; -/** - * AbstractQueue is an abstract class which implements some of the methods in - * {@link Queue}. The provided implementations of {@code add, remove} and - * {@code element} are based on {@code offer, poll}, and {@code peek} except - * that they throw exceptions to indicate some error instead of returning true - * or false. - * - * @param - * the type of the element in the collection. - */ +/// AbstractQueue is an abstract class which implements some of the methods in +/// `Queue`. The provided implementations of `add, remove` and +/// `element` are based on `offer, poll`, and `peek` except +/// that they throw exceptions to indicate some error instead of returning true +/// or false. +/// +/// @param +/// the type of the element in the collection. public abstract class AbstractQueue extends AbstractCollection implements Queue { - /** - * Constructor to be used by subclasses. - */ + /// Constructor to be used by subclasses. protected AbstractQueue() { super(); } - /** - * Adds an element to the queue. - * - * @param o - * the element to be added to the queue. - * @return {@code true} if the operation succeeds, otherwise {@code false}. - * @throws IllegalStateException - * if the element is not allowed to be added to the queue. - */ + /// Adds an element to the queue. + /// + /// #### Parameters + /// + /// - `o`: the element to be added to the queue. + /// + /// #### Returns + /// + /// `true` if the operation succeeds, otherwise `false`. + /// + /// #### Throws + /// + /// - `IllegalStateException`: if the element is not allowed to be added to the queue. @Override public boolean add(E o) { if (null == o) { @@ -56,23 +56,28 @@ public boolean add(E o) { throw new IllegalStateException(); } - /** - * Adds all the elements of a collection to the queue. If the collection is - * the queue itself, then an IllegalArgumentException will be thrown. If - * during the process, some runtime exception is thrown, then those elements - * in the collection which have already successfully been added will remain - * in the queue. The result of the method is undefined if the collection is - * modified during the process of the method. - * - * @param c - * the collection to be added to the queue. - * @return {@code true} if the operation succeeds, otherwise {@code false}. - * @throws NullPointerException - * if the collection or any element of it is null. - * @throws IllegalArgumentException - * If the collection to be added to the queue is the queue - * itself. - */ + /// Adds all the elements of a collection to the queue. If the collection is + /// the queue itself, then an IllegalArgumentException will be thrown. If + /// during the process, some runtime exception is thrown, then those elements + /// in the collection which have already successfully been added will remain + /// in the queue. The result of the method is undefined if the collection is + /// modified during the process of the method. + /// + /// #### Parameters + /// + /// - `c`: the collection to be added to the queue. + /// + /// #### Returns + /// + /// `true` if the operation succeeds, otherwise `false`. + /// + /// #### Throws + /// + /// - `NullPointerException`: if the collection or any element of it is null. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// If the collection to be added to the queue is the queue + /// itself. @Override public boolean addAll(Collection c) { if (null == c) { @@ -84,13 +89,15 @@ public boolean addAll(Collection c) { return super.addAll(c); } - /** - * Removes the element at the head of the queue and returns it. - * - * @return the element at the head of the queue. - * @throws NoSuchElementException - * if the queue is empty. - */ + /// Removes the element at the head of the queue and returns it. + /// + /// #### Returns + /// + /// the element at the head of the queue. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the queue is empty. public E remove() { E o = poll(); if (null == o) { @@ -99,13 +106,15 @@ public E remove() { return o; } - /** - * Returns but does not remove the element at the head of the queue. - * - * @return the element at the head of the queue. - * @throws NoSuchElementException - * if the queue is empty. - */ + /// Returns but does not remove the element at the head of the queue. + /// + /// #### Returns + /// + /// the element at the head of the queue. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the queue is empty. public E element() { E o = peek(); if (null == o) { @@ -114,9 +123,7 @@ public E element() { return o; } - /** - * Removes all elements of the queue, leaving it empty. - */ + /// Removes all elements of the queue, leaving it empty. @Override public void clear() { E o; diff --git a/Ports/CLDC11/src/java/util/AbstractSequentialList.java b/Ports/CLDC11/src/java/util/AbstractSequentialList.java index e630da2a58..2aab850091 100644 --- a/Ports/CLDC11/src/java/util/AbstractSequentialList.java +++ b/Ports/CLDC11/src/java/util/AbstractSequentialList.java @@ -17,18 +17,16 @@ package java.util; -/** - * AbstractSequentialList is an abstract implementation of the List interface. - * This implementation does not support adding. A subclass must implement the - * abstract method listIterator(). - * - * @since 1.2 - */ +/// AbstractSequentialList is an abstract implementation of the List interface. +/// This implementation does not support adding. A subclass must implement the +/// abstract method listIterator(). +/// +/// #### Since +/// +/// 1.2 public abstract class AbstractSequentialList extends AbstractList { - /** - * Constructs a new instance of this AbstractSequentialList. - */ + /// Constructs a new instance of this AbstractSequentialList. protected AbstractSequentialList() { super(); } diff --git a/Ports/CLDC11/src/java/util/AbstractSet.java b/Ports/CLDC11/src/java/util/AbstractSet.java index 1515550250..6d70be8c0e 100644 --- a/Ports/CLDC11/src/java/util/AbstractSet.java +++ b/Ports/CLDC11/src/java/util/AbstractSet.java @@ -17,34 +17,37 @@ package java.util; -/** - * An AbstractSet is an abstract implementation of the Set interface. This - * implementation does not support adding. A subclass must implement the - * abstract methods iterator() and size(). - * - * @since 1.2 - */ +/// An AbstractSet is an abstract implementation of the Set interface. This +/// implementation does not support adding. A subclass must implement the +/// abstract methods iterator() and size(). +/// +/// #### Since +/// +/// 1.2 public abstract class AbstractSet extends AbstractCollection implements Set { - /** - * Constructs a new instance of this AbstractSet. - */ + /// Constructs a new instance of this AbstractSet. protected AbstractSet() { super(); } - /** - * Compares the specified object to this Set and returns true if they are - * equal. The object must be an instance of Set and contain the same - * objects. - * - * @param object - * the object to compare with this set. - * @return {@code true} if the specified object is equal to this set, - * {@code false} otherwise - * @see #hashCode - */ + /// Compares the specified object to this Set and returns true if they are + /// equal. The object must be an instance of Set and contain the same + /// objects. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this set. + /// + /// #### Returns + /// + /// @return `true` if the specified object is equal to this set, + /// `false` otherwise + /// + /// #### See also + /// + /// - #hashCode @Override public boolean equals(Object object) { if (this == object) { @@ -64,14 +67,17 @@ public boolean equals(Object object) { return false; } - /** - * Returns the hash code for this set. Two set which are equal must return - * the same value. This implementation calculates the hash code by adding - * each element's hash code. - * - * @return the hash code of this set. - * @see #equals - */ + /// Returns the hash code for this set. Two set which are equal must return + /// the same value. This implementation calculates the hash code by adding + /// each element's hash code. + /// + /// #### Returns + /// + /// the hash code of this set. + /// + /// #### See also + /// + /// - #equals @Override public int hashCode() { int result = 0; @@ -83,17 +89,21 @@ public int hashCode() { return result; } - /** - * Removes all occurrences in this collection which are contained in the - * specified collection. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this collection was modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this collection is not supported. - */ + /// Removes all occurrences in this collection which are contained in the + /// specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// @return `true` if this collection was modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this collection is not supported. @Override public boolean removeAll(Collection collection) { boolean result = false; diff --git a/Ports/CLDC11/src/java/util/ArrayDeque.java b/Ports/CLDC11/src/java/util/ArrayDeque.java index b9a9e1c7e6..d54eb2b787 100644 --- a/Ports/CLDC11/src/java/util/ArrayDeque.java +++ b/Ports/CLDC11/src/java/util/ArrayDeque.java @@ -17,19 +17,19 @@ package java.util; -/** - * An implementation of Deque, backed by an array. - * - * ArrayDeques have no size limit, can not contain null element, and they are - * not thread-safe. - * - * All optional operations are supported, and the elements can be any objects. - * - * @param - * the type of elements in this collection - * - * @since 1.6 - */ +/// An implementation of Deque, backed by an array. +/// +/// ArrayDeques have no size limit, can not contain null element, and they are +/// not thread-safe. +/// +/// All optional operations are supported, and the elements can be any objects. +/// +/// @param +/// the type of elements in this collection +/// +/// #### Since +/// +/// 1.6 public class ArrayDeque extends AbstractCollection implements Deque { private static final int DEFAULT_SIZE = 16; @@ -172,20 +172,17 @@ public void remove() { } } - /** - * Constructs a new empty instance of ArrayDeque big enough for 16 elements. - */ + /// Constructs a new empty instance of ArrayDeque big enough for 16 elements. public ArrayDeque() { this(DEFAULT_SIZE); } - /** - * Constructs a new empty instance of ArrayDeque big enough for specified - * number of elements. - * - * @param minSize - * the smallest size of the ArrayDeque - */ + /// Constructs a new empty instance of ArrayDeque big enough for specified + /// number of elements. + /// + /// #### Parameters + /// + /// - `minSize`: the smallest size of the ArrayDeque @SuppressWarnings("unchecked") public ArrayDeque(final int minSize) { int size = countInitSize(minSize); @@ -202,16 +199,17 @@ private int countInitSize(final int minSize) { return -1; } - /** - * Constructs a new instance of ArrayDeque containing the elements of the - * specified collection, with the order returned by the collection's - * iterator. - * - * @param c - * the source of the elements - * @throws NullPointerException - * if the collection is null - */ + /// Constructs a new instance of ArrayDeque containing the elements of the + /// specified collection, with the order returned by the collection's + /// iterator. + /// + /// #### Parameters + /// + /// - `c`: the source of the elements + /// + /// #### Throws + /// + /// - `NullPointerException`: if the collection is null @SuppressWarnings("unchecked") public ArrayDeque(Collection c) { elements = (E[]) new Object[countInitSize(c.size())]; @@ -224,42 +222,57 @@ public ArrayDeque(Collection c) { } } - /** - * {@inheritDoc} - * - * @param e - * the element - * @throws NullPointerException - * if the element is null - * @see java.util.Deque#addFirst(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Deque#addFirst(java.lang.Object) public void addFirst(E e) { offerFirst(e); } - /** - * {@inheritDoc} - * - * @param e - * the element - * @throws NullPointerException - * if the element is null - * @see java.util.Deque#addLast(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Deque#addLast(java.lang.Object) public void addLast(E e) { addLastImpl(e); } - /** - * {@inheritDoc} - * - * @param e - * the element - * @return true - * @throws NullPointerException - * if the element is null - * @see java.util.Deque#offerFirst(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Deque#offerFirst(java.lang.Object) public boolean offerFirst(E e) { checkNull(e); checkAndExpand(); @@ -270,208 +283,284 @@ public boolean offerFirst(E e) { return true; } - /** - * {@inheritDoc} - * - * @param e - * the element - * @return true if the operation succeeds or false if it fails - * @throws NullPointerException - * if the element is null - * @see java.util.Deque#offerLast(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true if the operation succeeds or false if it fails + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Deque#offerLast(java.lang.Object) public boolean offerLast(E e) { return addLastImpl(e); } - /** - * Inserts the element at the tail of the deque. - * - * @param e - * the element - * @return true if the operation succeeds or false if it fails. - * @throws NullPointerException - * if the element is null - * @see java.util.Queue#offer(java.lang.Object) - */ + /// Inserts the element at the tail of the deque. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true if the operation succeeds or false if it fails. + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Queue#offer(java.lang.Object) public boolean offer(E e) { return addLastImpl(e); } - /** - * Inserts the element to the tail of the deque. - * - * @param e - * the element - * @return true - * @see java.util.AbstractCollection#add(java.lang.Object) - */ + /// Inserts the element to the tail of the deque. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true + /// + /// #### See also + /// + /// - java.util.AbstractCollection#add(java.lang.Object) @Override public boolean add(E e) { return addLastImpl(e); } - /** - * {@inheritDoc} - * - * @param e - * the element to push - * @throws NullPointerException - * if the element is null - * @see java.util.Deque#push(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `e`: the element to push + /// + /// #### Throws + /// + /// - `NullPointerException`: if the element is null + /// + /// #### See also + /// + /// - java.util.Deque#push(java.lang.Object) public void push(E e) { offerFirst(e); } - /** - * {@inheritDoc} - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Deque#removeFirst() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#removeFirst() public E removeFirst() { checkEmpty(); return removePollFirstImpl(); } - /** - * Gets and removes the head element of this deque. This method throws an - * exception if the deque is empty. - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Queue#remove() - */ + /// Gets and removes the head element of this deque. This method throws an + /// exception if the deque is empty. + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Queue#remove() public E remove() { return removeFirst(); } - /** - * {@inheritDoc} - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Deque#pop() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#pop() public E pop() { return removeFirst(); } - /** - * {@inheritDoc} - * - * @return the tail element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Deque#removeLast() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the tail element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#removeLast() public E removeLast() { checkEmpty(); return removeLastImpl(); } - /** - * {@inheritDoc} - * - * @return the head element or null if the deque is empty - * @see java.util.Deque#pollFirst() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the head element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#pollFirst() public E pollFirst() { return (status == DequeStatus.Empty) ? null : removePollFirstImpl(); } - /** - * Gets and removes the head element of this deque. This method returns null - * if the deque is empty. - * - * @return the head element or null if the deque is empty - * @see java.util.Queue#poll() - */ + /// Gets and removes the head element of this deque. This method returns null + /// if the deque is empty. + /// + /// #### Returns + /// + /// the head element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Queue#poll() public E poll() { return pollFirst(); } - /** - * {@inheritDoc} - * - * @return the tail element or null if the deque is empty - * @see java.util.Deque#pollLast() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the tail element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#pollLast() public E pollLast() { return (status == DequeStatus.Empty) ? null : removeLastImpl(); } - /** - * {@inheritDoc} - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Deque#getFirst() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#getFirst() public E getFirst() { checkEmpty(); return elements[front]; } - /** - * Gets but does not remove the head element of this deque. It throws an - * exception if the deque is empty. - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Queue#element() - */ + /// Gets but does not remove the head element of this deque. It throws an + /// exception if the deque is empty. + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Queue#element() public E element() { return getFirst(); } - /** - * {@inheritDoc} - * - * @return the tail element - * @throws NoSuchElementException - * if the deque is empty - * @see java.util.Deque#getLast() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the tail element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#getLast() public E getLast() { checkEmpty(); return elements[circularSmallerPos(rear)]; } - /** - * {@inheritDoc} - * - * @return the head element or null if the deque is empty - * @see java.util.Deque#peekFirst() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the head element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#peekFirst() public E peekFirst() { return (status == DequeStatus.Empty) ? null : elements[front]; } - /** - * Gets but not removes the head element of this deque. This method returns - * null if the deque is empty. - * - * @return the head element or null if the deque is empty - * @see java.util.Queue#peek() - */ + /// Gets but not removes the head element of this deque. This method returns + /// null if the deque is empty. + /// + /// #### Returns + /// + /// the head element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Queue#peek() public E peek() { return (status == DequeStatus.Empty) ? null : elements[front]; } - /** - * {@inheritDoc} - * - * @return the tail element or null if the deque is empty - * @see java.util.Deque#peekLast() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the tail element or null if the deque is empty + /// + /// #### See also + /// + /// - java.util.Deque#peekLast() public E peekLast() { return (status == DequeStatus.Empty) ? null : elements[circularSmallerPos(rear)]; @@ -524,12 +613,11 @@ private void checkAndExpand() { elements = newElements; } - /** - * Resets the status after adding or removing operation. - * - * @param adding - * if the method is called after an "adding" operation - */ + /// Resets the status after adding or removing operation. + /// + /// #### Parameters + /// + /// - `adding`: if the method is called after an "adding" operation private void resetStatus(boolean adding) { if (front == rear) { status = adding ? DequeStatus.Full : DequeStatus.Empty; @@ -567,43 +655,58 @@ private E removeLastImpl() { return element; } - /** - * {@inheritDoc} - * - * @param obj - * the element to be removed - * @return true if the operation succeeds or false if the deque does not - * contain the element - * @see java.util.Deque#removeFirstOccurrence(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `obj`: the element to be removed + /// + /// #### Returns + /// + /// @return true if the operation succeeds or false if the deque does not + /// contain the element + /// + /// #### See also + /// + /// - java.util.Deque#removeFirstOccurrence(java.lang.Object) public boolean removeFirstOccurrence(Object obj) { return removeFirstOccurrenceImpl(obj); } - /** - * Removes the first equivalent element of the specified object. If the - * deque does not contain the element, it is unchanged and returns false. - * - * @param obj - * the element to be removed - * @return true if the operation succeeds or false if the deque does not - * contain the element - * @see java.util.AbstractCollection#remove(java.lang.Object) - */ + /// Removes the first equivalent element of the specified object. If the + /// deque does not contain the element, it is unchanged and returns false. + /// + /// #### Parameters + /// + /// - `obj`: the element to be removed + /// + /// #### Returns + /// + /// @return true if the operation succeeds or false if the deque does not + /// contain the element + /// + /// #### See also + /// + /// - java.util.AbstractCollection#remove(java.lang.Object) @Override public boolean remove(Object obj) { return removeFirstOccurrenceImpl(obj); } - /** - * {@inheritDoc} - * - * @param obj - * the element to be removed - * @return true if the operation succeeds or false if the deque does not - * contain the element. - * @see java.util.Deque#removeLastOccurrence(java.lang.Object) - */ + /// {@inheritDoc} + /// + /// #### Parameters + /// + /// - `obj`: the element to be removed + /// + /// #### Returns + /// + /// @return true if the operation succeeds or false if the deque does not + /// contain the element. + /// + /// #### See also + /// + /// - java.util.Deque#removeLastOccurrence(java.lang.Object) public boolean removeLastOccurrence(final Object obj) { if (null != obj) { Iterator iter = descendingIterator(); @@ -656,12 +759,15 @@ private void removeInternal(final int current, final boolean frontShift) { resetStatus(false); } - /** - * Returns the size of the deque. - * - * @return the size of the deque - * @see java.util.AbstractCollection#size() - */ + /// Returns the size of the deque. + /// + /// #### Returns + /// + /// the size of the deque + /// + /// #### See also + /// + /// - java.util.AbstractCollection#size() @Override public int size() { if (status == DequeStatus.Full) { @@ -671,25 +777,33 @@ public int size() { : (rear + elements.length - front); } - /** - * Returns true if the deque has no elements. - * - * @return true if the deque has no elements, false otherwise - * @see java.util.AbstractCollection#isEmpty() - */ + /// Returns true if the deque has no elements. + /// + /// #### Returns + /// + /// true if the deque has no elements, false otherwise + /// + /// #### See also + /// + /// - java.util.AbstractCollection#isEmpty() @Override public boolean isEmpty() { return 0 == size(); } - /** - * Returns true if the specified element is in the deque. - * - * @param obj - * the element - * @return true if the element is in the deque, false otherwise - * @see java.util.AbstractCollection#contains(java.lang.Object) - */ + /// Returns true if the specified element is in the deque. + /// + /// #### Parameters + /// + /// - `obj`: the element + /// + /// #### Returns + /// + /// true if the element is in the deque, false otherwise + /// + /// #### See also + /// + /// - java.util.AbstractCollection#contains(java.lang.Object) @SuppressWarnings("cast") @Override public boolean contains(final Object obj) { @@ -704,11 +818,11 @@ public boolean contains(final Object obj) { return false; } - /** - * Empty the deque. - * - * @see java.util.AbstractCollection#clear() - */ + /// Empty the deque. + /// + /// #### See also + /// + /// - java.util.AbstractCollection#clear() @SuppressWarnings("cast") @Override public void clear() { @@ -724,25 +838,31 @@ public void clear() { modCount = 0; } - /** - * Returns the iterator of the deque. The elements will be ordered from head - * to tail. - * - * @return the iterator - * @see java.util.AbstractCollection#iterator() - */ + /// Returns the iterator of the deque. The elements will be ordered from head + /// to tail. + /// + /// #### Returns + /// + /// the iterator + /// + /// #### See also + /// + /// - java.util.AbstractCollection#iterator() @SuppressWarnings("synthetic-access") @Override public Iterator iterator() { return new ArrayDequeIterator(); } - /** - * {@inheritDoc} - * - * @return the reverse order Iterator - * @see java.util.Deque#descendingIterator() - */ + /// {@inheritDoc} + /// + /// #### Returns + /// + /// the reverse order Iterator + /// + /// #### See also + /// + /// - java.util.Deque#descendingIterator() public Iterator descendingIterator() { return new ReverseArrayDequeIterator(); } diff --git a/Ports/CLDC11/src/java/util/ArrayList.java b/Ports/CLDC11/src/java/util/ArrayList.java index dd92ede3c3..e6885dbe47 100644 --- a/Ports/CLDC11/src/java/util/ArrayList.java +++ b/Ports/CLDC11/src/java/util/ArrayList.java @@ -18,13 +18,13 @@ package java.util; -/** - * ArrayList is an implementation of {@link List}, backed by an array. All - * optional operations adding, removing, and replacing are supported. The - * elements can be any objects. - * - * @since 1.2 - */ +/// ArrayList is an implementation of `List`, backed by an array. All +/// optional operations adding, removing, and replacing are supported. The +/// elements can be any objects. +/// +/// #### Since +/// +/// 1.2 public class ArrayList extends AbstractList implements List, RandomAccess { private static final long serialVersionUID = 8683452581122892189L; @@ -35,20 +35,17 @@ public class ArrayList extends AbstractList implements List, RandomAcce private transient E[] array; - /** - * Constructs a new instance of {@code ArrayList} with ten capacity. - */ + /// Constructs a new instance of `ArrayList` with ten capacity. public ArrayList() { this(10); } - /** - * Constructs a new instance of {@code ArrayList} with the specified - * capacity. - * - * @param capacity - * the initial capacity of this {@code ArrayList}. - */ + /// Constructs a new instance of `ArrayList` with the specified + /// capacity. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of this `ArrayList`. public ArrayList(int capacity) { if (capacity < 0) { throw new IllegalArgumentException(); @@ -57,14 +54,13 @@ public ArrayList(int capacity) { array = newElementArray(capacity); } - /** - * Constructs a new instance of {@code ArrayList} containing the elements of - * the specified collection. The initial size of the {@code ArrayList} will - * be 10% larger than the size of the specified collection. - * - * @param collection - * the collection of elements to add. - */ + /// Constructs a new instance of `ArrayList` containing the elements of + /// the specified collection. The initial size of the `ArrayList` will + /// be 10% larger than the size of the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. public ArrayList(Collection collection) { firstIndex = 0; Object[] objects = toObjectArray(collection); @@ -96,19 +92,20 @@ private E[] newElementArray(int size) { return (E[]) new Object[size]; } - /** - * Inserts the specified object into this {@code ArrayList} at the specified - * location. The object is inserted before any previous element at the - * specified location. If the location is equal to the size of this - * {@code ArrayList}, the object is added at the end. - * - * @param location - * the index at which to insert the object. - * @param object - * the object to add. - * @throws IndexOutOfBoundsException - * when {@code location < 0 || > size()} - */ + /// Inserts the specified object into this `ArrayList` at the specified + /// location. The object is inserted before any previous element at the + /// specified location. If the location is equal to the size of this + /// `ArrayList`, the object is added at the end. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert the object. + /// + /// - `object`: the object to add. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when `location size()` @Override public void add(int location, E object) { if (location < 0 || location > size) { @@ -143,13 +140,15 @@ public void add(int location, E object) { modCount++; } - /** - * Adds the specified object at the end of this {@code ArrayList}. - * - * @param object - * the object to add. - * @return always true - */ + /// Adds the specified object at the end of this `ArrayList`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// always true @Override public boolean add(E object) { if (firstIndex + size == array.length) { @@ -161,20 +160,24 @@ public boolean add(E object) { return true; } - /** - * Inserts the objects in the specified collection at the specified location - * in this List. The objects are added in the order they are returned from - * the collection's iterator. - * - * @param location - * the index at which to insert. - * @param collection - * the collection of objects. - * @return {@code true} if this {@code ArrayList} is modified, {@code false} - * otherwise. - * @throws IndexOutOfBoundsException - * when {@code location < 0 || > size()} - */ + /// Inserts the objects in the specified collection at the specified location + /// in this List. The objects are added in the order they are returned from + /// the collection's iterator. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if this `ArrayList` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when `location size()` @Override public boolean addAll(int location, Collection collection) { if (location < 0 || location > size) { @@ -224,14 +227,16 @@ public boolean addAll(int location, Collection collection) { return true; } - /** - * Adds the objects in the specified collection to this {@code ArrayList}. - * - * @param collection - * the collection of objects. - * @return {@code true} if this {@code ArrayList} is modified, {@code false} - * otherwise. - */ + /// Adds the objects in the specified collection to this `ArrayList`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if this `ArrayList` is modified, `false` + /// otherwise. @Override public boolean addAll(Collection collection) { Object[] dumpArray = toObjectArray(collection); @@ -248,12 +253,13 @@ public boolean addAll(Collection collection) { return true; } - /** - * Removes all elements from this {@code ArrayList}, leaving it empty. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `ArrayList`, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size @Override public void clear() { if (size != 0) { @@ -268,14 +274,16 @@ public void clear() { } } - /** - * Searches this {@code ArrayList} for the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if {@code object} is an element of this - * {@code ArrayList}, {@code false} otherwise - */ + /// Searches this `ArrayList` for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if `object` is an element of this + /// `ArrayList`, `false` otherwise @Override public boolean contains(Object object) { int lastIndex = firstIndex + size; @@ -295,13 +303,12 @@ public boolean contains(Object object) { return false; } - /** - * Ensures that after this operation the {@code ArrayList} can hold the - * specified number of elements without further growing. - * - * @param minimumCapacity - * the minimum capacity asked for. - */ + /// Ensures that after this operation the `ArrayList` can hold the + /// specified number of elements without further growing. + /// + /// #### Parameters + /// + /// - `minimumCapacity`: the minimum capacity asked for. public void ensureCapacity(int minimumCapacity) { int required = minimumCapacity - array.length; if (required > 0) { @@ -452,15 +459,19 @@ public int lastIndexOf(Object object) { return -1; } - /** - * Removes the object at the specified location from this list. - * - * @param location - * the index of the object to remove. - * @return the removed object. - * @throws IndexOutOfBoundsException - * when {@code location < 0 || >= size()} - */ + /// Removes the object at the specified location from this list. + /// + /// #### Parameters + /// + /// - `location`: the index of the object to remove. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when `location = size()` @Override public E remove(int location) { E result; @@ -509,17 +520,18 @@ public boolean remove(Object object) { return false; } - /** - * Removes the objects in the specified range from the start to the end, but - * not including the end index. - * - * @param start - * the index at which to start removing. - * @param end - * the index one after the end of the range to remove. - * @throws IndexOutOfBoundsException - * when {@code start < 0, start > end} or {@code end > size()} - */ + /// Removes the objects in the specified range from the start to the end, but + /// not including the end index. + /// + /// #### Parameters + /// + /// - `start`: the index at which to start removing. + /// + /// - `end`: the index one after the end of the range to remove. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when `start end` or `end > size()` @Override protected void removeRange(int start, int end) { // REVIEW: does RI call this from remove(location) @@ -551,18 +563,22 @@ protected void removeRange(int start, int end) { modCount++; } - /** - * Replaces the element at the specified location in this {@code ArrayList} - * with the specified object. - * - * @param location - * the index at which to put the specified object. - * @param object - * the object to add. - * @return the previous element at the index. - * @throws IndexOutOfBoundsException - * when {@code location < 0 || >= size()} - */ + /// Replaces the element at the specified location in this `ArrayList` + /// with the specified object. + /// + /// #### Parameters + /// + /// - `location`: the index at which to put the specified object. + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// the previous element at the index. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when `location = size()` @Override public E set(int location, E object) { if (location < 0 || location >= size) { @@ -573,22 +589,22 @@ public E set(int location, E object) { return result; } - /** - * Returns the number of elements in this {@code ArrayList}. - * - * @return the number of elements in this {@code ArrayList}. - */ + /// Returns the number of elements in this `ArrayList`. + /// + /// #### Returns + /// + /// the number of elements in this `ArrayList`. @Override public int size() { return size; } - /** - * Returns a new array containing all elements contained in this - * {@code ArrayList}. - * - * @return an array of the elements from this {@code ArrayList} - */ + /// Returns a new array containing all elements contained in this + /// `ArrayList`. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList` @Override public Object[] toArray() { Object[] result = new Object[size]; @@ -596,21 +612,26 @@ public Object[] toArray() { return result; } - /** - * Returns an array containing all elements contained in this - * {@code ArrayList}. If the specified array is large enough to hold the - * elements, the specified array is used, otherwise an array of the same - * type is created. If the specified array is used and is larger than this - * {@code ArrayList}, the array element following the collection elements - * is set to null. - * - * @param contents - * the array. - * @return an array of the elements from this {@code ArrayList}. - * @throws ArrayStoreException - * when the type of an element in this {@code ArrayList} cannot - * be stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this + /// `ArrayList`. If the specified array is large enough to hold the + /// elements, the specified array is used, otherwise an array of the same + /// type is created. If the specified array is used and is larger than this + /// `ArrayList`, the array element following the collection elements + /// is set to null. + /// + /// #### Parameters + /// + /// - `contents`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `ArrayList`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// when the type of an element in this `ArrayList` cannot + /// be stored in the type of the specified array. @Override @SuppressWarnings("unchecked") public T[] toArray(T[] contents) { @@ -627,12 +648,12 @@ public T[] toArray(T[] contents) { return (T[])arr; } - /** - * Sets the capacity of this {@code ArrayList} to be the same as the current - * size. - * - * @see #size - */ + /// Sets the capacity of this `ArrayList` to be the same as the current + /// size. + /// + /// #### See also + /// + /// - #size public void trimToSize() { E[] newArray = newElementArray(size); System.arraycopy(array, firstIndex, newArray, 0, size); diff --git a/Ports/CLDC11/src/java/util/Arrays.java b/Ports/CLDC11/src/java/util/Arrays.java index c0cb5ce72d..6d6df670dc 100644 --- a/Ports/CLDC11/src/java/util/Arrays.java +++ b/Ports/CLDC11/src/java/util/Arrays.java @@ -20,11 +20,11 @@ import java.io.Serializable; import java.lang.reflect.Array; -/** - * {@code Arrays} contains static methods which operate on arrays. - * - * @since 1.2 - */ +/// `Arrays` contains static methods which operate on arrays. +/// +/// #### Since +/// +/// 1.2 public class Arrays { /* Specifies when to switch to insertion sort */ @@ -129,194 +129,227 @@ private Arrays() { /* empty */ } - /** - * Returns a {@code List} of the objects in the specified array. The size of the - * {@code List} cannot be modified, i.e. adding and removing are unsupported, but - * the elements can be set. Setting an element modifies the underlying - * array. - * - * @param array - * the array. - * @return a {@code List} of the elements of the specified array. - */ + /// Returns a `List` of the objects in the specified array. The size of the + /// `List` cannot be modified, i.e. adding and removing are unsupported, but + /// the elements can be set. Setting an element modifies the underlying + /// array. + /// + /// #### Parameters + /// + /// - `array`: the array. + /// + /// #### Returns + /// + /// a `List` of the elements of the specified array. public static List asList(T... array) { return new ArrayList(array); } - /** - * Performs a binary search for the specified element in the specified - * ascending sorted array. Searching in an unsorted array has an undefined - * result. It's also undefined which element is found if there are multiple - * occurrences of the same element. - * - * @param array - * the sorted {@code byte} array to search. - * @param value - * the {@code byte} element to find. - * @return the non-negative index of the element, or a negative index which - * is {@code -index - 1} where the element would be inserted. - */ + /// Performs a binary search for the specified element in the specified + /// ascending sorted array. Searching in an unsorted array has an undefined + /// result. It's also undefined which element is found if there are multiple + /// occurrences of the same element. + /// + /// #### Parameters + /// + /// - `array`: the sorted `byte` array to search. + /// + /// - `value`: the `byte` element to find. + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is `-index - 1` where the element would be inserted. public static int binarySearch(byte[] array, byte value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted char array to search - * @param value - * the char element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted char array to search + /// + /// - `value`: the char element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(char[] array, char value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted double array to search - * @param value - * the double element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted double array to search + /// + /// - `value`: the double element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(double[] array, double value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted float array to search - * @param value - * the float element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted float array to search + /// + /// - `value`: the float element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(float[] array, float value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted int array to search - * @param value - * the int element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted int array to search + /// + /// - `value`: the int element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(int[] array, int value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted long array to search - * @param value - * the long element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted long array to search + /// + /// - `value`: the long element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(long[] array, long value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted Object array to search - * @param object - * the Object element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * - * @exception ClassCastException - * when an element in the array or the search element does - * not implement Comparable, or cannot be compared to each - * other - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted Object array to search + /// + /// - `object`: the Object element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when an element in the array or the search element does + /// not implement Comparable, or cannot be compared to each + /// other @SuppressWarnings("unchecked") public static int binarySearch(Object[] array, Object object) { return binarySearch(array, 0, array.length, object); } - /** - * Performs a binary search for the specified element in the specified - * sorted array using the Comparator to compare elements. - * - * @param - * type of object - * - * @param array - * the sorted Object array to search - * @param object - * the char element to find - * @param comparator - * the Comparator - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * - * @exception ClassCastException - * when an element in the array and the search element cannot - * be compared to each other using the Comparator - */ + /// Performs a binary search for the specified element in the specified + /// sorted array using the Comparator to compare elements. + /// + /// @param + /// type of object + /// + /// #### Parameters + /// + /// - `array`: the sorted Object array to search + /// + /// - `object`: the char element to find + /// + /// - `comparator`: the Comparator + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when an element in the array and the search element cannot + /// be compared to each other using the Comparator public static int binarySearch(T[] array, T object, Comparator comparator) { return binarySearch(array, 0, array.length, object, comparator); } - /** - * Performs a binary search for the specified element in the specified - * sorted array. - * - * @param array - * the sorted short array to search - * @param value - * the short element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - */ + /// Performs a binary search for the specified element in the specified + /// sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted short array to search + /// + /// - `value`: the short element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted public static int binarySearch(short[] array, short value) { return binarySearch(array, 0, array.length, value); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted byte array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the byte element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted byte array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the byte element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(byte[] array, int startIndex, int endIndex, byte value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -343,27 +376,36 @@ public static int binarySearch(byte[] array, int startIndex, int endIndex, return -mid - (value < array[mid] ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted char array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the char element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted char array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the char element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(char[] array, int startIndex, int endIndex, char value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -390,27 +432,36 @@ public static int binarySearch(char[] array, int startIndex, int endIndex, return -mid - (value < array[mid] ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted double array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the double element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted double array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the double element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(double[] array, int startIndex, int endIndex, double value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -438,27 +489,36 @@ public static int binarySearch(double[] array, int startIndex, return -mid - (lessThan(value, array[mid]) ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted float array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the float element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted float array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the float element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(float[] array, int startIndex, int endIndex, float value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -486,27 +546,36 @@ public static int binarySearch(float[] array, int startIndex, int endIndex, return -mid - (lessThan(value, array[mid]) ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted int array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the int element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted int array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the int element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(int[] array, int startIndex, int endIndex, int value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -533,27 +602,36 @@ public static int binarySearch(int[] array, int startIndex, int endIndex, return -mid - (value < array[mid] ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted long array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the long element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted long array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the long element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(long[] array, int startIndex, int endIndex, long value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -580,30 +658,40 @@ public static int binarySearch(long[] array, int startIndex, int endIndex, return -mid - (value < array[mid] ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted Object array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param object - * the object element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws ClassCastException - * when an element in the array or the search element does not - * implement Comparable, or cannot be compared to each other - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted Object array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `object`: the object element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the array or the search element does not + /// implement Comparable, or cannot be compared to each other + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 @SuppressWarnings("unchecked") public static int binarySearch(Object[] array, int startIndex, int endIndex, Object object) { @@ -635,34 +723,45 @@ public static int binarySearch(Object[] array, int startIndex, return -mid - (result >= 0 ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array using the Comparator to compare elements. - * - * @param - * type of object - * @param array - * the sorted Object array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param object - * the value element to find - * @param comparator - * the Comparator - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws ClassCastException - * when an element in the array and the search element cannot be - * compared to each other using the Comparator - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array using the Comparator to compare elements. + /// + /// @param + /// type of object + /// + /// #### Parameters + /// + /// - `array`: the sorted Object array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `object`: the value element to find + /// + /// - `comparator`: the Comparator + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the array and the search element cannot be + /// compared to each other using the Comparator + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(T[] array, int startIndex, int endIndex, T object, Comparator comparator) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -693,27 +792,36 @@ public static int binarySearch(T[] array, int startIndex, int endIndex, return -mid - (result >= 0 ? 1 : 2); } - /** - * Performs a binary search for the specified element in a part of the - * specified sorted array. - * - * @param array - * the sorted short array to search - * @param startIndex - * the inclusive start index - * @param endIndex - * the exclusive end index - * @param value - * the short element to find - * @return the non-negative index of the element, or a negative index which - * is the -index - 1 where the element would be inserted - * @throws IllegalArgumentException - - * if startIndex is bigger than endIndex - * @throws ArrayIndexOutOfBoundsException - - * if startIndex is smaller than zero or or endIndex is bigger - * than length of array - * @since 1.6 - */ + /// Performs a binary search for the specified element in a part of the + /// specified sorted array. + /// + /// #### Parameters + /// + /// - `array`: the sorted short array to search + /// + /// - `startIndex`: the inclusive start index + /// + /// - `endIndex`: the exclusive end index + /// + /// - `value`: the short element to find + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the -index - 1 where the element would be inserted + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException - + /// if startIndex is bigger than endIndex + /// + /// - `ArrayIndexOutOfBoundsException`: @throws ArrayIndexOutOfBoundsException - + /// if startIndex is smaller than zero or or endIndex is bigger + /// than length of array + /// + /// #### Since + /// + /// 1.6 public static int binarySearch(short[] array, int startIndex, int endIndex, short value) { checkIndexForBinarySearch(array.length, startIndex, endIndex); @@ -740,16 +848,15 @@ public static int binarySearch(short[] array, int startIndex, int endIndex, return -mid - (value < array[mid] ? 1 : 2); } - /** - * Fills the array with the given value. - * - * @param length - * length of the array - * @param start - * start index - * @param end - * end index - */ + /// Fills the array with the given value. + /// + /// #### Parameters + /// + /// - `length`: length of the array + /// + /// - `start`: start index + /// + /// - `end`: end index private static void checkIndexForBinarySearch(int length, int start, int end) { if (start > end) { throw new IllegalArgumentException(); @@ -759,35 +866,36 @@ private static void checkIndexForBinarySearch(int length, int start, int end) { } } - /** - * Fills the specified array with the specified element. - * @param array - * the {@code byte} array to fill. - * @param value - * the {@code byte} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `byte` array to fill. + /// + /// - `value`: the `byte` element. public static void fill(byte[] array, byte value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code byte} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code byte} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `byte` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `byte` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(byte[] array, int start, int end, byte value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -795,36 +903,36 @@ public static void fill(byte[] array, int start, int end, byte value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code short} array to fill. - * @param value - * the {@code short} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `short` array to fill. + /// + /// - `value`: the `short` element. public static void fill(short[] array, short value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code short} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code short} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `short` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `short` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(short[] array, int start, int end, short value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -832,36 +940,36 @@ public static void fill(short[] array, int start, int end, short value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code char} array to fill. - * @param value - * the {@code char} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `char` array to fill. + /// + /// - `value`: the `char` element. public static void fill(char[] array, char value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code char} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code char} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `char` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `char` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(char[] array, int start, int end, char value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -869,36 +977,36 @@ public static void fill(char[] array, int start, int end, char value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code int} array to fill. - * @param value - * the {@code int} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `int` array to fill. + /// + /// - `value`: the `int` element. public static void fill(int[] array, int value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code int} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code int} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `int` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `int` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(int[] array, int start, int end, int value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -906,36 +1014,36 @@ public static void fill(int[] array, int start, int end, int value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code long} array to fill. - * @param value - * the {@code long} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `long` array to fill. + /// + /// - `value`: the `long` element. public static void fill(long[] array, long value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code long} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code long} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `long` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `long` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(long[] array, int start, int end, long value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -943,36 +1051,36 @@ public static void fill(long[] array, int start, int end, long value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code float} array to fill. - * @param value - * the {@code float} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `float` array to fill. + /// + /// - `value`: the `float` element. public static void fill(float[] array, float value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code float} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code float} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `float` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `float` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(float[] array, int start, int end, float value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -980,36 +1088,36 @@ public static void fill(float[] array, int start, int end, float value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code double} array to fill. - * @param value - * the {@code double} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `double` array to fill. + /// + /// - `value`: the `double` element. public static void fill(double[] array, double value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code double} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code double} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `double` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `double` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(double[] array, int start, int end, double value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -1017,36 +1125,36 @@ public static void fill(double[] array, int start, int end, double value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code boolean} array to fill. - * @param value - * the {@code boolean} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `boolean` array to fill. + /// + /// - `value`: the `boolean` element. public static void fill(boolean[] array, boolean value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code boolean} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code boolean} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `boolean` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `boolean` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(boolean[] array, int start, int end, boolean value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -1054,36 +1162,36 @@ public static void fill(boolean[] array, int start, int end, boolean value) { } } - /** - * Fills the specified array with the specified element. - * - * @param array - * the {@code Object} array to fill. - * @param value - * the {@code Object} element. - */ + /// Fills the specified array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to fill. + /// + /// - `value`: the `Object` element. public static void fill(Object[] array, Object value) { for (int i = 0; i < array.length; i++) { array[i] = value; } } - /** - * Fills the specified range in the array with the specified element. - * - * @param array - * the {@code Object} array to fill. - * @param start - * the first index to fill. - * @param end - * the last + 1 index to fill. - * @param value - * the {@code Object} element. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Fills the specified range in the array with the specified element. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to fill. + /// + /// - `start`: the first index to fill. + /// + /// - `end`: the last + 1 index to fill. + /// + /// - `value`: the `Object` element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void fill(Object[] array, int start, int end, Object value) { checkBounds(array.length, start, end); for (int i = start; i < end; i++) { @@ -1091,22 +1199,24 @@ public static void fill(Object[] array, int start, int end, Object value) { } } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code boolean} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Boolean}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `boolean` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Boolean`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(boolean[] array) { if (array == null) { return 0; @@ -1119,22 +1229,24 @@ public static int hashCode(boolean[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * not-null {@code int} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Integer}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// not-null `int` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Integer`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(int[] array) { if (array == null) { return 0; @@ -1147,22 +1259,24 @@ public static int hashCode(int[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code short} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Short}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `short` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Short`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(short[] array) { if (array == null) { return 0; @@ -1175,22 +1289,24 @@ public static int hashCode(short[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code char} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Character}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `char` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Character`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(char[] array) { if (array == null) { return 0; @@ -1203,22 +1319,24 @@ public static int hashCode(char[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code byte} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Byte}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `byte` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Byte`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(byte[] array) { if (array == null) { return 0; @@ -1231,22 +1349,24 @@ public static int hashCode(byte[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code long} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Long}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `long` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Long`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(long[] array) { if (array == null) { return 0; @@ -1263,22 +1383,24 @@ public static int hashCode(long[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code float} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Float}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `float` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Float`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(float[] array) { if (array == null) { return 0; @@ -1294,22 +1416,24 @@ public static int hashCode(float[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. For any two - * {@code double} arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the - * {@link List#hashCode()}} method which is invoked on a {@link List}} - * containing a sequence of {@link Double}} instances representing the - * elements of array in the same order. If the array is {@code null}, the return - * value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. For any two + /// `double` arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the + /// `List#hashCode()`} method which is invoked on a `List`} + /// containing a sequence of `Double`} instances representing the + /// elements of array in the same order. If the array is `null`, the return + /// value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(double[] array) { if (array == null) { return 0; @@ -1327,26 +1451,28 @@ public static int hashCode(double[] array) { return hashCode; } - /** - * Returns a hash code based on the contents of the given array. If the - * array contains other arrays as its elements, the hash code is based on - * their identities not their contents. So it is acceptable to invoke this - * method on an array that contains itself as an element, either directly or - * indirectly. - *

- * For any two arrays {@code a} and {@code b}, if - * {@code Arrays.equals(a, b)} returns {@code true}, it means - * that the return value of {@code Arrays.hashCode(a)} equals - * {@code Arrays.hashCode(b)}. - *

- * The value returned by this method is the same value as the method - * Arrays.asList(array).hashCode(). If the array is {@code null}, the return value - * is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the contents of the given array. If the + /// array contains other arrays as its elements, the hash code is based on + /// their identities not their contents. So it is acceptable to invoke this + /// method on an array that contains itself as an element, either directly or + /// indirectly. + /// + /// For any two arrays `a` and `b`, if + /// `Arrays.equals(a, b)` returns `true`, it means + /// that the return value of `Arrays.hashCode(a)` equals + /// `Arrays.hashCode(b)`. + /// + /// The value returned by this method is the same value as the method + /// Arrays.asList(array).hashCode(). If the array is `null`, the return value + /// is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int hashCode(Object[] array) { if (array == null) { return 0; @@ -1365,33 +1491,35 @@ public static int hashCode(Object[] array) { return hashCode; } - /** - * Returns a hash code based on the "deep contents" of the given array. If - * the array contains other arrays as its elements, the hash code is based - * on their contents not their identities. So it is not acceptable to invoke - * this method on an array that contains itself as an element, either - * directly or indirectly. - *

- * For any two arrays {@code a} and {@code b}, if - * {@code Arrays.deepEquals(a, b)} returns {@code true}, it - * means that the return value of {@code Arrays.deepHashCode(a)} equals - * {@code Arrays.deepHashCode(b)}. - *

- * The computation of the value returned by this method is similar to that - * of the value returned by {@link List#hashCode()}} invoked on a - * {@link List}} containing a sequence of instances representing the - * elements of array in the same order. The difference is: If an element e - * of array is itself an array, its hash code is computed by calling the - * appropriate overloading of {@code Arrays.hashCode(e)} if e is an array of a - * primitive type, or by calling {@code Arrays.deepHashCode(e)} recursively if e is - * an array of a reference type. The value returned by this method is the - * same value as the method {@code Arrays.asList(array).hashCode()}. If the array is - * {@code null}, the return value is 0. - * - * @param array - * the array whose hash code to compute. - * @return the hash code for {@code array}. - */ + /// Returns a hash code based on the "deep contents" of the given array. If + /// the array contains other arrays as its elements, the hash code is based + /// on their contents not their identities. So it is not acceptable to invoke + /// this method on an array that contains itself as an element, either + /// directly or indirectly. + /// + /// For any two arrays `a` and `b`, if + /// `Arrays.deepEquals(a, b)` returns `true`, it + /// means that the return value of `Arrays.deepHashCode(a)` equals + /// `Arrays.deepHashCode(b)`. + /// + /// The computation of the value returned by this method is similar to that + /// of the value returned by `List#hashCode()`} invoked on a + /// `List`} containing a sequence of instances representing the + /// elements of array in the same order. The difference is: If an element e + /// of array is itself an array, its hash code is computed by calling the + /// appropriate overloading of `Arrays.hashCode(e)` if e is an array of a + /// primitive type, or by calling `Arrays.deepHashCode(e)` recursively if e is + /// an array of a reference type. The value returned by this method is the + /// same value as the method `Arrays.asList(array).hashCode()`. If the array is + /// `null`, the return value is 0. + /// + /// #### Parameters + /// + /// - `array`: the array whose hash code to compute. + /// + /// #### Returns + /// + /// the hash code for `array`. public static int deepHashCode(Object[] array) { if (array == null) { return 0; @@ -1413,17 +1541,19 @@ private static int deepHashCodeElement(Object element) { return element.hashCode(); } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code byte} array. - * @param array2 - * the second {@code byte} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `byte` array. + /// + /// - `array2`: the second `byte` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(byte[] array1, byte[] array2) { if (array1 == array2) { return true; @@ -1439,17 +1569,19 @@ public static boolean equals(byte[] array1, byte[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code short} array. - * @param array2 - * the second {@code short} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `short` array. + /// + /// - `array2`: the second `short` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(short[] array1, short[] array2) { if (array1 == array2) { return true; @@ -1465,17 +1597,19 @@ public static boolean equals(short[] array1, short[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code char} array. - * @param array2 - * the second {@code char} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `char` array. + /// + /// - `array2`: the second `char` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(char[] array1, char[] array2) { if (array1 == array2) { return true; @@ -1491,17 +1625,19 @@ public static boolean equals(char[] array1, char[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code int} array. - * @param array2 - * the second {@code int} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `int` array. + /// + /// - `array2`: the second `int` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(int[] array1, int[] array2) { if (array1 == array2) { return true; @@ -1517,17 +1653,19 @@ public static boolean equals(int[] array1, int[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code long} array. - * @param array2 - * the second {@code long} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `long` array. + /// + /// - `array2`: the second `long` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(long[] array1, long[] array2) { if (array1 == array2) { return true; @@ -1543,19 +1681,24 @@ public static boolean equals(long[] array1, long[] array2) { return true; } - /** - * Compares the two arrays. The values are compared in the same manner as - * {@code Float.equals()}. - * - * @param array1 - * the first {@code float} array. - * @param array2 - * the second {@code float} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - * @see Float#equals(Object) - */ + /// Compares the two arrays. The values are compared in the same manner as + /// `Float.equals()`. + /// + /// #### Parameters + /// + /// - `array1`: the first `float` array. + /// + /// - `array2`: the second `float` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. + /// + /// #### See also + /// + /// - Float#equals(Object) public static boolean equals(float[] array1, float[] array2) { if (array1 == array2) { return true; @@ -1572,19 +1715,24 @@ public static boolean equals(float[] array1, float[] array2) { return true; } - /** - * Compares the two arrays. The values are compared in the same manner as - * {@code Double.equals()}. - * - * @param array1 - * the first {@code double} array. - * @param array2 - * the second {@code double} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - * @see Double#equals(Object) - */ + /// Compares the two arrays. The values are compared in the same manner as + /// `Double.equals()`. + /// + /// #### Parameters + /// + /// - `array1`: the first `double` array. + /// + /// - `array2`: the second `double` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. + /// + /// #### See also + /// + /// - Double#equals(Object) public static boolean equals(double[] array1, double[] array2) { if (array1 == array2) { return true; @@ -1601,17 +1749,19 @@ public static boolean equals(double[] array1, double[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code boolean} array. - * @param array2 - * the second {@code boolean} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `boolean` array. + /// + /// - `array2`: the second `boolean` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal, `false` otherwise. public static boolean equals(boolean[] array1, boolean[] array2) { if (array1 == array2) { return true; @@ -1627,17 +1777,19 @@ public static boolean equals(boolean[] array1, boolean[] array2) { return true; } - /** - * Compares the two arrays. - * - * @param array1 - * the first {@code Object} array. - * @param array2 - * the second {@code Object} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal according to {@code equals()}, {@code false} otherwise. - */ + /// Compares the two arrays. + /// + /// #### Parameters + /// + /// - `array1`: the first `Object` array. + /// + /// - `array2`: the second `Object` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal according to `equals()`, `false` otherwise. public static boolean equals(Object[] array1, Object[] array2) { if (array1 == array2) { return true; @@ -1654,42 +1806,44 @@ public static boolean equals(Object[] array1, Object[] array2) { return true; } - /** - * Returns {@code true} if the two given arrays are deeply equal to one another. - * Unlike the method {@code equals(Object[] array1, Object[] array2)}, this method - * is appropriate for use for nested arrays of arbitrary depth. - *

- * Two array references are considered deeply equal if they are both {@code null}, - * or if they refer to arrays that have the same length and the elements at - * each index in the two arrays are equal. - *

- * Two {@code null} elements {@code element1} and {@code element2} are possibly deeply equal if any - * of the following conditions satisfied: - *

- * {@code element1} and {@code element2} are both arrays of object reference types, and - * {@code Arrays.deepEquals(element1, element2)} would return {@code true}. - *

- * {@code element1} and {@code element2} are arrays of the same primitive type, and the - * appropriate overloading of {@code Arrays.equals(element1, element2)} would return - * {@code true}. - *

- * {@code element1 == element2} - *

- * {@code element1.equals(element2)} would return {@code true}. - *

- * Note that this definition permits {@code null} elements at any depth. - *

- * If either of the given arrays contain themselves as elements, the - * behavior of this method is uncertain. - * - * @param array1 - * the first {@code Object} array. - * @param array2 - * the second {@code Object} array. - * @return {@code true} if both arrays are {@code null} or if the arrays have the - * same length and the elements at each index in the two arrays are - * equal according to {@code equals()}, {@code false} otherwise. - */ + /// Returns `true` if the two given arrays are deeply equal to one another. + /// Unlike the method `equals(Object[] array1, Object[] array2)`, this method + /// is appropriate for use for nested arrays of arbitrary depth. + /// + /// Two array references are considered deeply equal if they are both `null`, + /// or if they refer to arrays that have the same length and the elements at + /// each index in the two arrays are equal. + /// + /// Two `null` elements `element1` and `element2` are possibly deeply equal if any + /// of the following conditions satisfied: + /// + /// `element1` and `element2` are both arrays of object reference types, and + /// `Arrays.deepEquals(element1, element2)` would return `true`. + /// + /// `element1` and `element2` are arrays of the same primitive type, and the + /// appropriate overloading of `Arrays.equals(element1, element2)` would return + /// `true`. + /// + /// `element1 == element2` + /// + /// `element1.equals(element2)` would return `true`. + /// + /// Note that this definition permits `null` elements at any depth. + /// + /// If either of the given arrays contain themselves as elements, the + /// behavior of this method is uncertain. + /// + /// #### Parameters + /// + /// - `array1`: the first `Object` array. + /// + /// - `array2`: the second `Object` array. + /// + /// #### Returns + /// + /// @return `true` if both arrays are `null` or if the arrays have the + /// same length and the elements at each index in the two arrays are + /// equal according to `equals()`, `false` otherwise. public static boolean deepEquals(Object[] array1, Object[] array2) { if (array1 == array2) { return true; @@ -1858,30 +2012,30 @@ private static int med3(short[] array, int a, int b, int c) { : a)); } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code byte} array to be sorted. - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `byte` array to be sorted. public static void sort(byte[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. - * - * @param array - * the {@code byte} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `byte` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(byte[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -1983,30 +2137,30 @@ private static void sort(int start, int end, byte[] array) { } } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code char} array to be sorted. - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `char` array to be sorted. public static void sort(char[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. - * - * @param array - * the {@code char} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `char` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(char[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2093,33 +2247,39 @@ private static void sort(int start, int end, char[] array) { } } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code double} array to be sorted. - * @see #sort(double[], int, int) - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `double` array to be sorted. + /// + /// #### See also + /// + /// - #sort(double[], int, int) public static void sort(double[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. The - * values are sorted according to the order imposed by {@code Double.compareTo()}. - * - * @param array - * the {@code double} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - * @see Double#compareTo(Double) - */ + /// Sorts the specified range in the array in ascending numerical order. The + /// values are sorted according to the order imposed by `Double.compareTo()`. + /// + /// #### Parameters + /// + /// - `array`: the `double` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. + /// + /// #### See also + /// + /// - Double#compareTo(Double) public static void sort(double[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2206,33 +2366,39 @@ private static void sort(int start, int end, double[] array) { } } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code float} array to be sorted. - * @see #sort(float[], int, int) - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `float` array to be sorted. + /// + /// #### See also + /// + /// - #sort(float[], int, int) public static void sort(float[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. The - * values are sorted according to the order imposed by {@code Float.compareTo()}. - * - * @param array - * the {@code float} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - * @see Float#compareTo(Float) - */ + /// Sorts the specified range in the array in ascending numerical order. The + /// values are sorted according to the order imposed by `Float.compareTo()`. + /// + /// #### Parameters + /// + /// - `array`: the `float` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. + /// + /// #### See also + /// + /// - Float#compareTo(Float) public static void sort(float[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2319,30 +2485,30 @@ private static void sort(int start, int end, float[] array) { } } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code int} array to be sorted. - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `int` array to be sorted. public static void sort(int[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. - * - * @param array - * the {@code int} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `int` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(int[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2429,30 +2595,30 @@ private static void sort(int start, int end, int[] array) { } } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code long} array to be sorted. - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `long` array to be sorted. public static void sort(long[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. - * - * @param array - * the {@code long} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `long` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(long[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2539,40 +2705,47 @@ private static void sort(int start, int end, long[] array) { } } - /** - * Sorts the specified array in ascending natural order. - * - * @param array - * the {@code Object} array to be sorted. - * @throws ClassCastException - * if an element in the array does not implement {@code Comparable} - * or if some elements cannot be compared to each other. - * @see #sort(Object[], int, int) - */ + /// Sorts the specified array in ascending natural order. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to be sorted. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if an element in the array does not implement `Comparable` + /// or if some elements cannot be compared to each other. + /// + /// #### See also + /// + /// - #sort(Object[], int, int) public static void sort(Object[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending natural order. All - * elements must implement the {@code Comparable} interface and must be - * comparable to each other without a {@code ClassCastException} being - * thrown. - * - * @param array - * the {@code Object} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws ClassCastException - * if an element in the array does not implement {@code Comparable} - * or some elements cannot be compared to each other. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending natural order. All + /// elements must implement the `Comparable` interface and must be + /// comparable to each other without a `ClassCastException` being + /// thrown. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if an element in the array does not implement `Comparable` + /// or some elements cannot be compared to each other. + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(Object[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -2595,38 +2768,41 @@ private static void sort(int start, int end, Object[] array) { } } - /** - * Swaps the elements at the given indices in the array. - * - * @param a - - * the index of one element to be swapped. - * @param b - - * the index of the other element to be swapped. - * @param arr - - * the array in which to swap elements. - */ + /// Swaps the elements at the given indices in the array. + /// + /// #### Parameters + /// + /// - `a`: @param a - + /// the index of one element to be swapped. + /// + /// - `b`: @param b - + /// the index of the other element to be swapped. + /// + /// - `arr`: @param arr - + /// the array in which to swap elements. private static void swap(int a, int b, Object[] arr) { Object tmp = arr[a]; arr[a] = arr[b]; arr[b] = tmp; } - /** - * Performs a sort on the section of the array between the given indices - * using a mergesort with exponential search algorithm (in which the merge - * is performed by exponential search). n*log(n) performance is guaranteed - * and in the average case it will be faster then any mergesort in which the - * merge is performed by linear search. - * - * @param in - - * the array for sorting. - * @param out - - * the result, sorted array. - * @param start - * the start index - * @param end - * the end index + 1 - */ + /// Performs a sort on the section of the array between the given indices + /// using a mergesort with exponential search algorithm (in which the merge + /// is performed by exponential search). n*log(n) performance is guaranteed + /// and in the average case it will be faster then any mergesort in which the + /// merge is performed by linear search. + /// + /// #### Parameters + /// + /// - `in`: @param in - + /// the array for sorting. + /// + /// - `out`: @param out - + /// the result, sorted array. + /// + /// - `start`: the start index + /// + /// - `end`: the end index + 1 @SuppressWarnings("unchecked") private static void mergeSort(Object[] in, Object[] out, int start, int end) { @@ -2692,24 +2868,26 @@ private static void mergeSort(Object[] in, Object[] out, int start, } } - /** - * Performs a sort on the section of the array between the given indices - * using a mergesort with exponential search algorithm (in which the merge - * is performed by exponential search). n*log(n) performance is guaranteed - * and in the average case it will be faster then any mergesort in which the - * merge is performed by linear search. - * - * @param in - - * the array for sorting. - * @param out - - * the result, sorted array. - * @param start - * the start index - * @param end - * the end index + 1 - * @param c - - * the comparator to determine the order of the array. - */ + /// Performs a sort on the section of the array between the given indices + /// using a mergesort with exponential search algorithm (in which the merge + /// is performed by exponential search). n*log(n) performance is guaranteed + /// and in the average case it will be faster then any mergesort in which the + /// merge is performed by linear search. + /// + /// #### Parameters + /// + /// - `in`: @param in - + /// the array for sorting. + /// + /// - `out`: @param out - + /// the result, sorted array. + /// + /// - `start`: the start index + /// + /// - `end`: the end index + 1 + /// + /// - `c`: @param c - + /// the comparator to determine the order of the array. @SuppressWarnings("unchecked") private static void mergeSort(Object[] in, Object[] out, int start, int end, Comparator c) { @@ -2774,29 +2952,28 @@ private static void mergeSort(Object[] in, Object[] out, int start, } } - /** - * Finds the place in the given range of specified sorted array, where the - * element should be inserted for getting sorted array. Uses exponential - * search algorithm. - * - * @param arr - - * the array with already sorted range - * - * @param val - - * object to be inserted - * - * @param l - - * the start index - * - * @param r - - * the end index - * - * @param bnd - - * possible values 0,-1. "-1" - val is located at index more then - * elements equals to val. "0" - val is located at index less - * then elements equals to val. - * - */ + /// Finds the place in the given range of specified sorted array, where the + /// element should be inserted for getting sorted array. Uses exponential + /// search algorithm. + /// + /// #### Parameters + /// + /// - `arr`: @param arr - + /// the array with already sorted range + /// + /// - `val`: @param val - + /// object to be inserted + /// + /// - `l`: @param l - + /// the start index + /// + /// - `r`: @param r - + /// the end index + /// + /// - `bnd`: @param bnd - + /// possible values 0,-1. "-1" - val is located at index more then + /// elements equals to val. "0" - val is located at index less + /// then elements equals to val. @SuppressWarnings("unchecked") private static int find(Object[] arr, java.lang.Comparable val, int bnd, int l, int r) { int m = l; @@ -2822,26 +2999,31 @@ private static int find(Object[] arr, java.lang.Comparable val, int bnd, int l, return l - 1; } - /** - * Finds the place of specified range of specified sorted array, where the - * element should be inserted for getting sorted array. Uses exponential - * search algorithm. - * - * @param arr - - * the array with already sorted range - * @param val - - * object to be inserted - * @param l - - * the start index - * @param r - - * the end index - * @param bnd - - * possible values 0,-1. "-1" - val is located at index more then - * elements equals to val. "0" - val is located at index less - * then elements equals to val. - * @param c - - * the comparator used to compare Objects - */ + /// Finds the place of specified range of specified sorted array, where the + /// element should be inserted for getting sorted array. Uses exponential + /// search algorithm. + /// + /// #### Parameters + /// + /// - `arr`: @param arr - + /// the array with already sorted range + /// + /// - `val`: @param val - + /// object to be inserted + /// + /// - `l`: @param l - + /// the start index + /// + /// - `r`: @param r - + /// the end index + /// + /// - `bnd`: @param bnd - + /// possible values 0,-1. "-1" - val is located at index more then + /// elements equals to val. "0" - val is located at index less + /// then elements equals to val. + /// + /// - `c`: @param c - + /// the comparator used to compare Objects @SuppressWarnings("unchecked") private static int find(Object[] arr, Object val, int bnd, int l, int r, Comparator c) { @@ -2891,21 +3073,25 @@ private static int charAt(String str, int i) { return str.charAt(i); } - /** - * Copies object from one array to another array with reverse of objects - * order. Source and destination arrays may be the same. - * - * @param src - - * the source array. - * @param from - - * starting position in the source array. - * @param dst - - * the destination array. - * @param to - - * starting position in the destination array. - * @param len - - * the number of array elements to be copied. - */ + /// Copies object from one array to another array with reverse of objects + /// order. Source and destination arrays may be the same. + /// + /// #### Parameters + /// + /// - `src`: @param src - + /// the source array. + /// + /// - `from`: @param from - + /// starting position in the source array. + /// + /// - `dst`: @param dst - + /// the destination array. + /// + /// - `to`: @param to - + /// starting position in the destination array. + /// + /// - `len`: @param len - + /// the number of array elements to be copied. private static void copySwap(Object[] src, int from, Object[] dst, int to, int len) { if (src == dst && from + len > to) { @@ -2925,39 +3111,46 @@ private static void copySwap(Object[] src, int from, Object[] dst, int to, } } - /** - * Performs a sort on the given String array. Elements will be re-ordered into - * ascending order. - * - * @param arr - - * the array to sort - * @param start - - * the start index - * @param end - - * the end index + 1 - */ + /// Performs a sort on the given String array. Elements will be re-ordered into + /// ascending order. + /// + /// #### Parameters + /// + /// - `arr`: @param arr - + /// the array to sort + /// + /// - `start`: @param start - + /// the start index + /// + /// - `end`: @param end - + /// the end index + 1 private static void stableStringSort(String[] arr, int start, int end) { stableStringSort(arr, arr, new String[end], start, end, 0); } - /** - * Performs a sort on the given String array. Elements will be re-ordered into - * ascending order. Uses a stable ternary quick sort algorithm. - * - * @param arr - - * the array to sort - * @param src - - * auxiliary array - * @param dst - - * auxiliary array - * @param start - - * the start index - * @param end - - * the end index + 1 - * @param chId - - * index of char for current sorting - */ + /// Performs a sort on the given String array. Elements will be re-ordered into + /// ascending order. Uses a stable ternary quick sort algorithm. + /// + /// #### Parameters + /// + /// - `arr`: @param arr - + /// the array to sort + /// + /// - `src`: @param src - + /// auxiliary array + /// + /// - `dst`: @param dst - + /// auxiliary array + /// + /// - `start`: @param start - + /// the start index + /// + /// - `end`: @param end - + /// the end index + 1 + /// + /// - `chId`: @param chId - + /// index of char for current sorting private static void stableStringSort(String[] arr, String[] src, String[] dst, int start, int end, int chId) { int length = end - start; @@ -3056,27 +3249,29 @@ private static void stableStringSort(String[] arr, String[] src, } } - /** - * Sorts the specified range in the array using the specified {@code Comparator}. - * All elements must be comparable to each other without a - * {@code ClassCastException} being thrown. - * - * @param array - * the {@code Object} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @param comparator - * the {@code Comparator}. - * @throws ClassCastException - * if elements in the array cannot be compared to each other - * using the {@code Comparator}. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array using the specified `Comparator`. + /// All elements must be comparable to each other without a + /// `ClassCastException` being thrown. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// - `comparator`: the `Comparator`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if elements in the array cannot be compared to each other + /// using the `Comparator`. + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(T[] array, int start, int end, Comparator comparator) { if (array == null) { @@ -3098,46 +3293,48 @@ private static void sort(int start, int end, T[] array, } } - /** - * Sorts the specified array using the specified {@code Comparator}. All elements - * must be comparable to each other without a {@code ClassCastException} being thrown. - * - * @param array - * the {@code Object} array to be sorted. - * @param comparator - * the {@code Comparator}. - * @throws ClassCastException - * if elements in the array cannot be compared to each other - * using the {@code Comparator}. - */ + /// Sorts the specified array using the specified `Comparator`. All elements + /// must be comparable to each other without a `ClassCastException` being thrown. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to be sorted. + /// + /// - `comparator`: the `Comparator`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if elements in the array cannot be compared to each other + /// using the `Comparator`. public static void sort(T[] array, Comparator comparator) { sort(0, array.length, array, comparator); } - /** - * Sorts the specified array in ascending numerical order. - * - * @param array - * the {@code short} array to be sorted. - */ + /// Sorts the specified array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `short` array to be sorted. public static void sort(short[] array) { sort(0, array.length, array); } - /** - * Sorts the specified range in the array in ascending numerical order. - * - * @param array - * the {@code short} array to be sorted. - * @param start - * the start index to sort. - * @param end - * the last + 1 index to sort. - * @throws IllegalArgumentException - * if {@code start > end}. - * @throws ArrayIndexOutOfBoundsException - * if {@code start < 0} or {@code end > array.length}. - */ + /// Sorts the specified range in the array in ascending numerical order. + /// + /// #### Parameters + /// + /// - `array`: the `short` array to be sorted. + /// + /// - `start`: the start index to sort. + /// + /// - `end`: the last + 1 index to sort. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `start > end`. + /// + /// - `ArrayIndexOutOfBoundsException`: if `start array.length`. public static void sort(short[] array, int start, int end) { if (array == null) { throw new NullPointerException(); @@ -3224,18 +3421,23 @@ private static void sort(int start, int end, short[] array) { } } - /** - * Creates a {@code String} representation of the {@code boolean[]} passed. - * The result is surrounded by brackets ({@code "[]"}), each - * element is converted to a {@code String} via the - * {@link String#valueOf(boolean)} and separated by {@code ", "}. - * If the array is {@code null}, then {@code "null"} is returned. - * - * @param array - * the {@code boolean} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `boolean[]` passed. + /// The result is surrounded by brackets (`"[]"`), each + /// element is converted to a `String` via the + /// `String#valueOf(boolean)` and separated by `", "`. + /// If the array is `null`, then `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `boolean` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(boolean[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3254,18 +3456,23 @@ public static String toString(boolean[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code byte[]} passed. The - * result is surrounded by brackets ({@code "[]"}), each element - * is converted to a {@code String} via the {@link String#valueOf(int)} and - * separated by {@code ", "}. If the array is {@code null}, then - * {@code "null"} is returned. - * - * @param array - * the {@code byte} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `byte[]` passed. The + /// result is surrounded by brackets (`"[]"`), each element + /// is converted to a `String` via the `String#valueOf(int)` and + /// separated by `", "`. If the array is `null`, then + /// `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `byte` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(byte[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3284,18 +3491,23 @@ public static String toString(byte[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code char[]} passed. The - * result is surrounded by brackets ({@code "[]"}), each element - * is converted to a {@code String} via the {@link String#valueOf(char)} and - * separated by {@code ", "}. If the array is {@code null}, then - * {@code "null"} is returned. - * - * @param array - * the {@code char} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `char[]` passed. The + /// result is surrounded by brackets (`"[]"`), each element + /// is converted to a `String` via the `String#valueOf(char)` and + /// separated by `", "`. If the array is `null`, then + /// `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `char` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(char[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3314,18 +3526,23 @@ public static String toString(char[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code double[]} passed. - * The result is surrounded by brackets ({@code "[]"}), each - * element is converted to a {@code String} via the - * {@link String#valueOf(double)} and separated by {@code ", "}. - * If the array is {@code null}, then {@code "null"} is returned. - * - * @param array - * the {@code double} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `double[]` passed. + /// The result is surrounded by brackets (`"[]"`), each + /// element is converted to a `String` via the + /// `String#valueOf(double)` and separated by `", "`. + /// If the array is `null`, then `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `double` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(double[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3344,18 +3561,23 @@ public static String toString(double[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code float[]} passed. - * The result is surrounded by brackets ({@code "[]"}), each - * element is converted to a {@code String} via the - * {@link String#valueOf(float)} and separated by {@code ", "}. - * If the array is {@code null}, then {@code "null"} is returned. - * - * @param array - * the {@code float} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `float[]` passed. + /// The result is surrounded by brackets (`"[]"`), each + /// element is converted to a `String` via the + /// `String#valueOf(float)` and separated by `", "`. + /// If the array is `null`, then `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `float` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(float[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3374,18 +3596,23 @@ public static String toString(float[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code int[]} passed. The - * result is surrounded by brackets ({@code "[]"}), each element - * is converted to a {@code String} via the {@link String#valueOf(int)} and - * separated by {@code ", "}. If the array is {@code null}, then - * {@code "null"} is returned. - * - * @param array - * the {@code int} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `int[]` passed. The + /// result is surrounded by brackets (`"[]"`), each element + /// is converted to a `String` via the `String#valueOf(int)` and + /// separated by `", "`. If the array is `null`, then + /// `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `int` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(int[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3404,18 +3631,23 @@ public static String toString(int[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code long[]} passed. The - * result is surrounded by brackets ({@code "[]"}), each element - * is converted to a {@code String} via the {@link String#valueOf(long)} and - * separated by {@code ", "}. If the array is {@code null}, then - * {@code "null"} is returned. - * - * @param array - * the {@code long} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `long[]` passed. The + /// result is surrounded by brackets (`"[]"`), each element + /// is converted to a `String` via the `String#valueOf(long)` and + /// separated by `", "`. If the array is `null`, then + /// `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `long` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(long[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3434,18 +3666,23 @@ public static String toString(long[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code short[]} passed. - * The result is surrounded by brackets ({@code "[]"}), each - * element is converted to a {@code String} via the - * {@link String#valueOf(int)} and separated by {@code ", "}. If - * the array is {@code null}, then {@code "null"} is returned. - * - * @param array - * the {@code short} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `short[]` passed. + /// The result is surrounded by brackets (`"[]"`), each + /// element is converted to a `String` via the + /// `String#valueOf(int)` and separated by `", "`. If + /// the array is `null`, then `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `short` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(short[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3464,18 +3701,23 @@ public static String toString(short[] array) { return sb.toString(); } - /** - * Creates a {@code String} representation of the {@code Object[]} passed. - * The result is surrounded by brackets ({@code "[]"}), each - * element is converted to a {@code String} via the - * {@link String#valueOf(Object)} and separated by {@code ", "}. - * If the array is {@code null}, then {@code "null"} is returned. - * - * @param array - * the {@code Object} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a `String` representation of the `Object[]` passed. + /// The result is surrounded by brackets (`"[]"`), each + /// element is converted to a `String` via the + /// `String#valueOf(Object)` and separated by `", "`. + /// If the array is `null`, then `"null"` is returned. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String toString(Object[] array) { if (array == null) { return "null"; //$NON-NLS-1$ @@ -3494,42 +3736,54 @@ public static String toString(Object[] array) { return sb.toString(); } - /** - * Creates a "deep" {@code String} representation of the - * {@code Object[]} passed, such that if the array contains other arrays, - * the {@code String} representation of those arrays is generated as well. - *

- * If any of the elements are primitive arrays, the generation is delegated - * to the other {@code toString} methods in this class. If any element - * contains a reference to the original array, then it will be represented - * as {@code "[...]"}. If an element is an {@code Object[]}, then its - * representation is generated by a recursive call to this method. All other - * elements are converted via the {@link String#valueOf(Object)} method. - * - * @param array - * the {@code Object} array to convert. - * @return the {@code String} representation of {@code array}. - * @since 1.5 - */ + /// Creates a *"deep"* `String` representation of the + /// `Object[]` passed, such that if the array contains other arrays, + /// the `String` representation of those arrays is generated as well. + /// + /// If any of the elements are primitive arrays, the generation is delegated + /// to the other `toString` methods in this class. If any element + /// contains a reference to the original array, then it will be represented + /// as `"[...]"`. If an element is an `Object[]`, then its + /// representation is generated by a recursive call to this method. All other + /// elements are converted via the `String#valueOf(Object)` method. + /// + /// #### Parameters + /// + /// - `array`: the `Object` array to convert. + /// + /// #### Returns + /// + /// the `String` representation of `array`. + /// + /// #### Since + /// + /// 1.5 public static String deepToString(Object[] array) { // delegate this to the recursive method return deepToStringImpl(array, new Object[] { array }, null); } - /** - * Implementation method used by {@link #deepToString(Object[])}. - * - * @param array - * the {@code Object[]} to dive into. - * @param origArrays - * the original {@code Object[]}; used to test for self - * references. - * @param sb - * the {@code StringBuilder} instance to append to or - * {@code null} one hasn't been created yet. - * @return the result. - * @see #deepToString(Object[]) - */ + /// Implementation method used by `#deepToString(Object[])`. + /// + /// #### Parameters + /// + /// - `array`: the `Object[]` to dive into. + /// + /// - `origArrays`: @param origArrays + /// the original `Object[]`; used to test for self + /// references. + /// + /// - `sb`: @param sb + /// the `StringBuilder` instance to append to or + /// `null` one hasn't been created yet. + /// + /// #### Returns + /// + /// the result. + /// + /// #### See also + /// + /// - #deepToString(Object[]) private static String deepToStringImpl(Object[] array, Object[] origArrays, StringBuffer sb) { if (array == null) { @@ -3582,17 +3836,19 @@ private static String deepToStringImpl(Object[] array, Object[] origArrays, return sb.toString(); } - /** - * Utility method used to assist the implementation of - * {@link #deepToString(Object[])}. - * - * @param origArrays - * An array of Object[] references. - * @param array - * An Object[] reference to look for in {@code origArrays}. - * @return A value of {@code true} if {@code array} is an - * element in {@code origArrays}. - */ + /// Utility method used to assist the implementation of + /// `#deepToString(Object[])`. + /// + /// #### Parameters + /// + /// - `origArrays`: An array of Object[] references. + /// + /// - `array`: An Object[] reference to look for in `origArrays`. + /// + /// #### Returns + /// + /// @return A value of `true` if `array` is an + /// element in `origArrays`. private static boolean deepToStringImplContains(Object[] origArrays, Object array) { if (origArrays == null || origArrays.length == 0) { @@ -3607,28 +3863,35 @@ private static boolean deepToStringImplContains(Object[] origArrays, } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is false. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is false. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static boolean[] copyOfRange(boolean[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3643,28 +3906,35 @@ public static boolean[] copyOfRange(boolean[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is (byte)0. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is (byte)0. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static byte[] copyOfRange(byte[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3679,28 +3949,35 @@ public static byte[] copyOfRange(byte[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is '\\u000'. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is '\\u000'. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static char[] copyOfRange(char[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3715,28 +3992,35 @@ public static char[] copyOfRange(char[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is 0d. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is 0d. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static double[] copyOfRange(double[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3751,28 +4035,35 @@ public static double[] copyOfRange(double[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is 0f. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is 0f. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static float[] copyOfRange(float[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3787,28 +4078,35 @@ public static float[] copyOfRange(float[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is 0. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is 0. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static int[] copyOfRange(int[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3823,28 +4121,35 @@ public static int[] copyOfRange(int[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is 0L. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is 0L. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static long[] copyOfRange(long[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { @@ -3859,28 +4164,35 @@ public static long[] copyOfRange(long[] original, int start, int end) { throw new IllegalArgumentException(); } - /** - * Copies elements in original array to a new array, from index - * start(inclusive) to end(exclusive). The first element (if any) in the new - * array is original[from], and other elements in the new array are in the - * original order. The padding value whose index is bigger than or equal to - * original.length - start is (short)0. - * - * @param original - * the original array - * @param start - * the start index, inclusive - * @param end - * the end index, exclusive, may bigger than length of the array - * @return the new copied array - * @throws ArrayIndexOutOfBoundsException - * if start is smaller than 0 or bigger than original.length - * @throws IllegalArgumentException - * if start is bigger than end - * @throws NullPointerException - * if original is null - * @since 1.6 - */ + /// Copies elements in original array to a new array, from index + /// start(inclusive) to end(exclusive). The first element (if any) in the new + /// array is original[from], and other elements in the new array are in the + /// original order. The padding value whose index is bigger than or equal to + /// original.length - start is (short)0. + /// + /// #### Parameters + /// + /// - `original`: the original array + /// + /// - `start`: the start index, inclusive + /// + /// - `end`: the end index, exclusive, may bigger than length of the array + /// + /// #### Returns + /// + /// the new copied array + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if start is smaller than 0 or bigger than original.length + /// + /// - `IllegalArgumentException`: if start is bigger than end + /// + /// - `NullPointerException`: if original is null + /// + /// #### Since + /// + /// 1.6 public static short[] copyOfRange(short[] original, int start, int end) { if (start <= end) { if (original.length >= start && 0 <= start) { diff --git a/Ports/CLDC11/src/java/util/BitSet.java b/Ports/CLDC11/src/java/util/BitSet.java index 47b25c5248..162043b6ac 100644 --- a/Ports/CLDC11/src/java/util/BitSet.java +++ b/Ports/CLDC11/src/java/util/BitSet.java @@ -18,12 +18,10 @@ package java.util; -/** - * The {@code BitSet} class implements a bit field. Each element in a - * {@code BitSet} can be on(1) or off(0). A {@code BitSet} is created with a - * given size and grows if this size is exceeded. Growth is always rounded to a - * 64 bit boundary. - */ +/// The `BitSet` class implements a bit field. Each element in a +/// `BitSet` can be on(1) or off(0). A `BitSet` is created with a +/// given size and grows if this size is exceeded. Growth is always rounded to a +/// 64 bit boundary. public class BitSet { private static final int OFFSET = 6; @@ -55,40 +53,56 @@ public class BitSet { private transient boolean isLengthActual; - /** - * Create a new {@code BitSet} with size equal to 64 bits. - * - * @see #clear(int) - * @see #set(int) - * @see #clear() - * @see #clear(int, int) - * @see #set(int, boolean) - * @see #set(int, int) - * @see #set(int, int, boolean) - */ + /// Create a new `BitSet` with size equal to 64 bits. + /// + /// #### See also + /// + /// - #clear(int) + /// + /// - #set(int) + /// + /// - #clear() + /// + /// - #clear(int, int) + /// + /// - #set(int, boolean) + /// + /// - #set(int, int) + /// + /// - #set(int, int, boolean) public BitSet() { bits = new long[1]; actualArrayLength = 0; isLengthActual = true; } - /** - * Create a new {@code BitSet} with size equal to nbits. If nbits is not a - * multiple of 64, then create a {@code BitSet} with size nbits rounded to - * the next closest multiple of 64. - * - * @param nbits - * the size of the bit set. - * @throws NegativeArraySizeException - * if {@code nbits} is negative. - * @see #clear(int) - * @see #set(int) - * @see #clear() - * @see #clear(int, int) - * @see #set(int, boolean) - * @see #set(int, int) - * @see #set(int, int, boolean) - */ + /// Create a new `BitSet` with size equal to nbits. If nbits is not a + /// multiple of 64, then create a `BitSet` with size nbits rounded to + /// the next closest multiple of 64. + /// + /// #### Parameters + /// + /// - `nbits`: the size of the bit set. + /// + /// #### Throws + /// + /// - `NegativeArraySizeException`: if `nbits` is negative. + /// + /// #### See also + /// + /// - #clear(int) + /// + /// - #set(int) + /// + /// - #clear() + /// + /// - #clear(int, int) + /// + /// - #set(int, boolean) + /// + /// - #set(int, int) + /// + /// - #set(int, int, boolean) public BitSet(int nbits) { if (nbits < 0) { throw new NegativeArraySizeException(); @@ -98,12 +112,11 @@ public BitSet(int nbits) { isLengthActual = true; } - /** - * Private constructor called from get(int, int) method - * - * @param bits - * the size of the bit set - */ + /// Private constructor called from get(int, int) method + /// + /// #### Parameters + /// + /// - `bits`: the size of the bit set private BitSet(long[] bits, boolean needClear, int actualArrayLength, boolean isLengthActual) { this.bits = bits; @@ -112,17 +125,22 @@ private BitSet(long[] bits, boolean needClear, int actualArrayLength, this.isLengthActual = isLengthActual; } - /** - * Compares the argument to this {@code BitSet} and returns whether they are - * equal. The object must be an instance of {@code BitSet} with the same - * bits set. - * - * @param obj - * the {@code BitSet} object to compare. - * @return a {@code boolean} indicating whether or not this {@code BitSet} and - * {@code obj} are equal. - * @see #hashCode - */ + /// Compares the argument to this `BitSet` and returns whether they are + /// equal. The object must be an instance of `BitSet` with the same + /// bits set. + /// + /// #### Parameters + /// + /// - `obj`: the `BitSet` object to compare. + /// + /// #### Returns + /// + /// @return a `boolean` indicating whether or not this `BitSet` and + /// `obj` are equal. + /// + /// #### See also + /// + /// - #hashCode @Override public boolean equals(Object obj) { if (this == obj) { @@ -165,28 +183,31 @@ public boolean equals(Object obj) { return false; } - /** - * Increase the size of the internal array to accommodate {@code pos} bits. - * The new array max index will be a multiple of 64. - * - * @param len - * the index the new array needs to be able to access. - */ + /// Increase the size of the internal array to accommodate `pos` bits. + /// The new array max index will be a multiple of 64. + /// + /// #### Parameters + /// + /// - `len`: the index the new array needs to be able to access. private final void growLength(int len) { long[] tempBits = new long[Math.max(len, bits.length * 2)]; System.arraycopy(bits, 0, tempBits, 0, this.actualArrayLength); bits = tempBits; } - /** - * Computes the hash code for this {@code BitSet}. If two {@code BitSet}s are equal - * the have to return the same result for {@code hashCode()}. - * - * @return the {@code int} representing the hash code for this bit - * set. - * @see #equals - * @see java.util.Hashtable - */ + /// Computes the hash code for this `BitSet`. If two `BitSet`s are equal + /// the have to return the same result for `hashCode()`. + /// + /// #### Returns + /// + /// @return the `int` representing the hash code for this bit + /// set. + /// + /// #### See also + /// + /// - #equals + /// + /// - java.util.Hashtable @Override public int hashCode() { long x = 1234; @@ -196,24 +217,37 @@ public int hashCode() { return (int) ((x >> 32) ^ x); } - /** - * Retrieves the bit at index {@code pos}. Grows the {@code BitSet} if - * {@code pos > size}. - * - * @param pos - * the index of the bit to be retrieved. - * @return {@code true} if the bit at {@code pos} is set, - * {@code false} otherwise. - * @throws IndexOutOfBoundsException - * if {@code pos} is negative. - * @see #clear(int) - * @see #set(int) - * @see #clear() - * @see #clear(int, int) - * @see #set(int, boolean) - * @see #set(int, int) - * @see #set(int, int, boolean) - */ + /// Retrieves the bit at index `pos`. Grows the `BitSet` if + /// `pos > size`. + /// + /// #### Parameters + /// + /// - `pos`: the index of the bit to be retrieved. + /// + /// #### Returns + /// + /// @return `true` if the bit at `pos` is set, + /// `false` otherwise. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `pos` is negative. + /// + /// #### See also + /// + /// - #clear(int) + /// + /// - #set(int) + /// + /// - #clear() + /// + /// - #clear(int, int) + /// + /// - #set(int, boolean) + /// + /// - #set(int, int) + /// + /// - #set(int, int, boolean) public boolean get(int pos) { if (pos < 0) { // Negative index specified @@ -227,21 +261,29 @@ public boolean get(int pos) { return false; } - /** - * Retrieves the bits starting from {@code pos1} to {@code pos2} and returns - * back a new bitset made of these bits. Grows the {@code BitSet} if - * {@code pos2 > size}. - * - * @param pos1 - * beginning position. - * @param pos2 - * ending position. - * @return new bitset of the range specified. - * @throws IndexOutOfBoundsException - * if {@code pos1} or {@code pos2} is negative, or if - * {@code pos2} is smaller than {@code pos1}. - * @see #get(int) - */ + /// Retrieves the bits starting from `pos1` to `pos2` and returns + /// back a new bitset made of these bits. Grows the `BitSet` if + /// `pos2 > size`. + /// + /// #### Parameters + /// + /// - `pos1`: beginning position. + /// + /// - `pos2`: ending position. + /// + /// #### Returns + /// + /// new bitset of the range specified. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `pos1` or `pos2` is negative, or if + /// `pos2` is smaller than `pos1`. + /// + /// #### See also + /// + /// - #get(int) public BitSet get(int pos1, int pos2) { if (pos1 < 0 || pos2 < 0 || pos2 < pos1) { throw new IndexOutOfBoundsException("" + pos1 + " and: " + pos2); @@ -301,18 +343,24 @@ public BitSet get(int pos1, int pos2) { newbits[actualLen - 1] != 0); } - /** - * Sets the bit at index {@code pos} to 1. Grows the {@code BitSet} if - * {@code pos > size}. - * - * @param pos - * the index of the bit to set. - * @throws IndexOutOfBoundsException - * if {@code pos} is negative. - * @see #clear(int) - * @see #clear() - * @see #clear(int, int) - */ + /// Sets the bit at index `pos` to 1. Grows the `BitSet` if + /// `pos > size`. + /// + /// #### Parameters + /// + /// - `pos`: the index of the bit to set. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `pos` is negative. + /// + /// #### See also + /// + /// - #clear(int) + /// + /// - #clear() + /// + /// - #clear(int, int) public void set(int pos) { if (pos < 0) { throw new IndexOutOfBoundsException("" + pos); @@ -330,18 +378,22 @@ public void set(int pos) { needClear(); } - /** - * Sets the bit at index {@code pos} to {@code val}. Grows the - * {@code BitSet} if {@code pos > size}. - * - * @param pos - * the index of the bit to set. - * @param val - * value to set the bit. - * @throws IndexOutOfBoundsException - * if {@code pos} is negative. - * @see #set(int) - */ + /// Sets the bit at index `pos` to `val`. Grows the + /// `BitSet` if `pos > size`. + /// + /// #### Parameters + /// + /// - `pos`: the index of the bit to set. + /// + /// - `val`: value to set the bit. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `pos` is negative. + /// + /// #### See also + /// + /// - #set(int) public void set(int pos, boolean val) { if (val) { set(pos); @@ -350,19 +402,24 @@ public void set(int pos, boolean val) { } } - /** - * Sets the bits starting from {@code pos1} to {@code pos2}. Grows the - * {@code BitSet} if {@code pos2 > size}. - * - * @param pos1 - * beginning position. - * @param pos2 - * ending position. - * @throws IndexOutOfBoundsException - * if {@code pos1} or {@code pos2} is negative, or if - * {@code pos2} is smaller than {@code pos1}. - * @see #set(int) - */ + /// Sets the bits starting from `pos1` to `pos2`. Grows the + /// `BitSet` if `pos2 > size`. + /// + /// #### Parameters + /// + /// - `pos1`: beginning position. + /// + /// - `pos2`: ending position. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `pos1` or `pos2` is negative, or if + /// `pos2` is smaller than `pos1`. + /// + /// #### See also + /// + /// - #set(int) public void set(int pos1, int pos2) { if (pos1 < 0 || pos2 < 0 || pos2 < pos1) { throw new IndexOutOfBoundsException("" + pos1 + " and: " + pos2); @@ -401,21 +458,26 @@ private void needClear() { this.needClear = true; } - /** - * Sets the bits starting from {@code pos1} to {@code pos2} to the given - * {@code val}. Grows the {@code BitSet} if {@code pos2 > size}. - * - * @param pos1 - * beginning position. - * @param pos2 - * ending position. - * @param val - * value to set these bits. - * @throws IndexOutOfBoundsException - * if {@code pos1} or {@code pos2} is negative, or if - * {@code pos2} is smaller than {@code pos1}. - * @see #set(int,int) - */ + /// Sets the bits starting from `pos1` to `pos2` to the given + /// `val`. Grows the `BitSet` if `pos2 > size`. + /// + /// #### Parameters + /// + /// - `pos1`: beginning position. + /// + /// - `pos2`: ending position. + /// + /// - `val`: value to set these bits. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `pos1` or `pos2` is negative, or if + /// `pos2` is smaller than `pos1`. + /// + /// #### See also + /// + /// - #set(int,int) public void set(int pos1, int pos2, boolean val) { if (val) { set(pos1, pos2); @@ -424,12 +486,13 @@ public void set(int pos1, int pos2, boolean val) { } } - /** - * Clears all the bits in this {@code BitSet}. - * - * @see #clear(int) - * @see #clear(int, int) - */ + /// Clears all the bits in this `BitSet`. + /// + /// #### See also + /// + /// - #clear(int) + /// + /// - #clear(int, int) public void clear() { if (needClear) { for (int i = 0; i < bits.length; i++) { @@ -441,16 +504,20 @@ public void clear() { } } - /** - * Clears the bit at index {@code pos}. Grows the {@code BitSet} if - * {@code pos > size}. - * - * @param pos - * the index of the bit to clear. - * @throws IndexOutOfBoundsException - * if {@code pos} is negative. - * @see #clear(int, int) - */ + /// Clears the bit at index `pos`. Grows the `BitSet` if + /// `pos > size`. + /// + /// #### Parameters + /// + /// - `pos`: the index of the bit to clear. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `pos` is negative. + /// + /// #### See also + /// + /// - #clear(int, int) public void clear(int pos) { if (pos < 0) { // Negative index specified @@ -469,19 +536,24 @@ public void clear(int pos) { } } - /** - * Clears the bits starting from {@code pos1} to {@code pos2}. Grows the - * {@code BitSet} if {@code pos2 > size}. - * - * @param pos1 - * beginning position. - * @param pos2 - * ending position. - * @throws IndexOutOfBoundsException - * if {@code pos1} or {@code pos2} is negative, or if - * {@code pos2} is smaller than {@code pos1}. - * @see #clear(int) - */ + /// Clears the bits starting from `pos1` to `pos2`. Grows the + /// `BitSet` if `pos2 > size`. + /// + /// #### Parameters + /// + /// - `pos1`: beginning position. + /// + /// - `pos2`: ending position. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `pos1` or `pos2` is negative, or if + /// `pos2` is smaller than `pos1`. + /// + /// #### See also + /// + /// - #clear(int) public void clear(int pos1, int pos2) { if (pos1 < 0 || pos2 < 0 || pos2 < pos1) { throw new IndexOutOfBoundsException("" + pos1 + " and: " + pos2); @@ -517,16 +589,20 @@ public void clear(int pos1, int pos2) { } } - /** - * Flips the bit at index {@code pos}. Grows the {@code BitSet} if - * {@code pos > size}. - * - * @param pos - * the index of the bit to flip. - * @throws IndexOutOfBoundsException - * if {@code pos} is negative. - * @see #flip(int, int) - */ + /// Flips the bit at index `pos`. Grows the `BitSet` if + /// `pos > size`. + /// + /// #### Parameters + /// + /// - `pos`: the index of the bit to flip. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `pos` is negative. + /// + /// #### See also + /// + /// - #flip(int, int) public void flip(int pos) { if (pos < 0) { throw new IndexOutOfBoundsException("" + pos); @@ -544,19 +620,24 @@ public void flip(int pos) { needClear(); } - /** - * Flips the bits starting from {@code pos1} to {@code pos2}. Grows the - * {@code BitSet} if {@code pos2 > size}. - * - * @param pos1 - * beginning position. - * @param pos2 - * ending position. - * @throws IndexOutOfBoundsException - * if {@code pos1} or {@code pos2} is negative, or if - * {@code pos2} is smaller than {@code pos1}. - * @see #flip(int) - */ + /// Flips the bits starting from `pos1` to `pos2`. Grows the + /// `BitSet` if `pos2 > size`. + /// + /// #### Parameters + /// + /// - `pos1`: beginning position. + /// + /// - `pos2`: ending position. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `pos1` or `pos2` is negative, or if + /// `pos2` is smaller than `pos1`. + /// + /// #### See also + /// + /// - #flip(int) public void flip(int pos1, int pos2) { if (pos1 < 0 || pos2 < 0 || pos2 < pos1) { throw new IndexOutOfBoundsException("" + pos1 + " and: " + pos2); @@ -591,15 +672,17 @@ public void flip(int pos1, int pos2) { needClear(); } - /** - * Checks if these two {@code BitSet}s have at least one bit set to true in the same - * position. - * - * @param bs - * {@code BitSet} used to calculate the intersection. - * @return {@code true} if bs intersects with this {@code BitSet}, - * {@code false} otherwise. - */ + /// Checks if these two `BitSet`s have at least one bit set to true in the same + /// position. + /// + /// #### Parameters + /// + /// - `bs`: `BitSet` used to calculate the intersection. + /// + /// #### Returns + /// + /// @return `true` if bs intersects with this `BitSet`, + /// `false` otherwise. public boolean intersects(BitSet bs) { long[] bsBits = bs.bits; int length1 = actualArrayLength, length2 = bs.actualArrayLength; @@ -621,15 +704,18 @@ public boolean intersects(BitSet bs) { return false; } - /** - * Performs the logical AND of this {@code BitSet} with another - * {@code BitSet}. The values of this {@code BitSet} are changed accordingly. - * - * @param bs - * {@code BitSet} to AND with. - * @see #or - * @see #xor - */ + /// Performs the logical AND of this `BitSet` with another + /// `BitSet`. The values of this `BitSet` are changed accordingly. + /// + /// #### Parameters + /// + /// - `bs`: `BitSet` to AND with. + /// + /// #### See also + /// + /// - #or + /// + /// - #xor public void and(BitSet bs) { long[] bsBits = bs.bits; if (!needClear) { @@ -652,13 +738,12 @@ public void and(BitSet bs) { isLengthActual = !((actualArrayLength > 0) && (bits[actualArrayLength - 1] == 0)); } - /** - * Clears all bits in the receiver which are also set in the parameter - * {@code BitSet}. The values of this {@code BitSet} are changed accordingly. - * - * @param bs - * {@code BitSet} to ANDNOT with. - */ + /// Clears all bits in the receiver which are also set in the parameter + /// `BitSet`. The values of this `BitSet` are changed accordingly. + /// + /// #### Parameters + /// + /// - `bs`: `BitSet` to ANDNOT with. public void andNot(BitSet bs) { long[] bsBits = bs.bits; if (!needClear) { @@ -676,15 +761,18 @@ public void andNot(BitSet bs) { isLengthActual = !((actualArrayLength > 0) && (bits[actualArrayLength - 1] == 0)); } - /** - * Performs the logical OR of this {@code BitSet} with another {@code BitSet}. - * The values of this {@code BitSet} are changed accordingly. - * - * @param bs - * {@code BitSet} to OR with. - * @see #xor - * @see #and - */ + /// Performs the logical OR of this `BitSet` with another `BitSet`. + /// The values of this `BitSet` are changed accordingly. + /// + /// #### Parameters + /// + /// - `bs`: `BitSet` to OR with. + /// + /// #### See also + /// + /// - #xor + /// + /// - #and public void or(BitSet bs) { int bsActualLen = bs.getActualArrayLength(); if (bsActualLen > bits.length) { @@ -709,15 +797,18 @@ public void or(BitSet bs) { needClear(); } - /** - * Performs the logical XOR of this {@code BitSet} with another {@code BitSet}. - * The values of this {@code BitSet} are changed accordingly. - * - * @param bs - * {@code BitSet} to XOR with. - * @see #or - * @see #and - */ + /// Performs the logical XOR of this `BitSet` with another `BitSet`. + /// The values of this `BitSet` are changed accordingly. + /// + /// #### Parameters + /// + /// - `bs`: `BitSet` to XOR with. + /// + /// #### See also + /// + /// - #or + /// + /// - #and public void xor(BitSet bs) { int bsActualLen = bs.getActualArrayLength(); if (bsActualLen > bits.length) { @@ -742,21 +833,24 @@ public void xor(BitSet bs) { needClear(); } - /** - * Returns the number of bits this {@code BitSet} has. - * - * @return the number of bits contained in this {@code BitSet}. - * @see #length - */ + /// Returns the number of bits this `BitSet` has. + /// + /// #### Returns + /// + /// the number of bits contained in this `BitSet`. + /// + /// #### See also + /// + /// - #length public int size() { return bits.length << OFFSET; } - /** - * Returns the number of bits up to and including the highest bit set. - * - * @return the length of the {@code BitSet}. - */ + /// Returns the number of bits up to and including the highest bit set. + /// + /// #### Returns + /// + /// the length of the `BitSet`. public int length() { int idx = actualArrayLength - 1; while (idx >= 0 && bits[idx] == 0) { @@ -787,12 +881,12 @@ private final int getActualArrayLength() { return actualArrayLength; } - /** - * Returns a string containing a concise, human-readable description of the - * receiver. - * - * @return a comma delimited list of the indices of all bits that are set. - */ + /// Returns a string containing a concise, human-readable description of the + /// receiver. + /// + /// #### Returns + /// + /// a comma delimited list of the indices of all bits that are set. @Override public String toString() { StringBuffer sb = new StringBuffer(bits.length / 2); @@ -819,13 +913,15 @@ public String toString() { return sb.toString(); } - /** - * Returns the position of the first bit that is {@code true} on or after {@code pos}. - * - * @param pos - * the starting position (inclusive). - * @return -1 if there is no bits that are set to {@code true} on or after {@code pos}. - */ + /// Returns the position of the first bit that is `true` on or after `pos`. + /// + /// #### Parameters + /// + /// - `pos`: the starting position (inclusive). + /// + /// #### Returns + /// + /// -1 if there is no bits that are set to `true` on or after `pos`. public int nextSetBit(int pos) { if (pos < 0) { throw new IndexOutOfBoundsException("" + pos); @@ -864,14 +960,16 @@ public int nextSetBit(int pos) { return -1; } - /** - * Returns the position of the first bit that is {@code false} on or after {@code pos}. - * - * @param pos - * the starting position (inclusive). - * @return the position of the next bit set to {@code false}, even if it is further - * than this {@code BitSet}'s size. - */ + /// Returns the position of the first bit that is `false` on or after `pos`. + /// + /// #### Parameters + /// + /// - `pos`: the starting position (inclusive). + /// + /// #### Returns + /// + /// @return the position of the next bit set to `false`, even if it is further + /// than this `BitSet`'s size. public int nextClearBit(int pos) { if (pos < 0) { throw new IndexOutOfBoundsException("" + pos); @@ -911,12 +1009,12 @@ public int nextClearBit(int pos) { return bssize; } - /** - * Returns true if all the bits in this {@code BitSet} are set to false. - * - * @return {@code true} if the {@code BitSet} is empty, - * {@code false} otherwise. - */ + /// Returns true if all the bits in this `BitSet` are set to false. + /// + /// #### Returns + /// + /// @return `true` if the `BitSet` is empty, + /// `false` otherwise. public boolean isEmpty() { if (!needClear) { return true; @@ -930,11 +1028,11 @@ public boolean isEmpty() { return true; } - /** - * Returns the number of bits that are {@code true} in this {@code BitSet}. - * - * @return the number of {@code true} bits in the set. - */ + /// Returns the number of bits that are `true` in this `BitSet`. + /// + /// #### Returns + /// + /// the number of `true` bits in the set. public int cardinality() { if (!needClear) { return 0; diff --git a/Ports/CLDC11/src/java/util/Calendar.java b/Ports/CLDC11/src/java/util/Calendar.java index ccba1b7a5c..3d76bee305 100644 --- a/Ports/CLDC11/src/java/util/Calendar.java +++ b/Ports/CLDC11/src/java/util/Calendar.java @@ -22,405 +22,301 @@ * have any questions. */ package java.util; -/** - * Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A Date object represents a specific instant in time with millisecond precision. See Date for information about the Date class.) - * Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. - * Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type. - * A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). - * When computing a Date from time fields, there may be insufficient information to compute the Date (such as only year and month but no day in the month). - * Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. Note: The ambiguity in interpretation of what day midnight belongs to, is resolved as so: midnight "belongs" to the following day. 23:59 on Dec 31, 1969 00:00 on Jan 1, 1970. 12:00 PM is midday, and 12:00 AM is midnight. 11:59 PM on Jan 1 12:00 AM on Jan 2 12:01 AM on Jan 2. 11:59 AM on Mar 10 12:00 PM on Mar 10 12:01 PM on Mar 10. 24:00 or greater are invalid. Hours greater than 12 are invalid in AM/PM mode. Setting the time will never change the date. - * If equivalent times are entered in AM/PM or 24 hour mode, equality will be determined by the actual time rather than the entered time. - * This class has been subset for J2ME based on the JDK 1.3 Calendar class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class. - * Version: CLDC 1.1 02/01/2002 (based on JDK 1.3) See Also:Date, TimeZone - */ +/// Calendar is an abstract base class for converting between a Date object and a set of integer fields such as YEAR, MONTH, DAY, HOUR, and so on. (A Date object represents a specific instant in time with millisecond precision. See Date for information about the Date class.) +/// Subclasses of Calendar interpret a Date according to the rules of a specific calendar system. +/// Like other locale-sensitive classes, Calendar provides a class method, getInstance, for getting a generally useful object of this type. +/// A Calendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). +/// When computing a Date from time fields, there may be insufficient information to compute the Date (such as only year and month but no day in the month). +/// Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., YEAR = 1970, MONTH = JANUARY, DATE = 1, etc. Note: The ambiguity in interpretation of what day midnight belongs to, is resolved as so: midnight "belongs" to the following day. 23:59 on Dec 31, 1969 00:00 on Jan 1, 1970. 12:00 PM is midday, and 12:00 AM is midnight. 11:59 PM on Jan 1 12:00 AM on Jan 2 12:01 AM on Jan 2. 11:59 AM on Mar 10 12:00 PM on Mar 10 12:01 PM on Mar 10. 24:00 or greater are invalid. Hours greater than 12 are invalid in AM/PM mode. Setting the time will never change the date. +/// If equivalent times are entered in AM/PM or 24 hour mode, equality will be determined by the actual time rather than the entered time. +/// This class has been subset for J2ME based on the JDK 1.3 Calendar class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class. +/// Version: CLDC 1.1 02/01/2002 (based on JDK 1.3) See Also:Date, TimeZone public abstract class Calendar{ - /** - * Value of the AM_PM field indicating the period of the day from midnight to just before noon. - * See Also:Constant Field Values - */ + /// Value of the AM_PM field indicating the period of the day from midnight to just before noon. + /// See Also:Constant Field Values public static final int AM=0; - /** - * Field number for get and set indicating whether the HOUR is before or after noon. E.g., at 10:04:15.250 PM the AM_PM is PM. - * See Also:AM, PM, HOUR, Constant Field Values - */ + /// Field number for get and set indicating whether the HOUR is before or after noon. E.g., at 10:04:15.250 PM the AM_PM is PM. + /// See Also:AM, PM, HOUR, Constant Field Values public static final int AM_PM=9; - /** - * Value of the MONTH field indicating the fourth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the fourth month of the year. + /// See Also:Constant Field Values public static final int APRIL=3; - /** - * Value of the MONTH field indicating the eighth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the eighth month of the year. + /// See Also:Constant Field Values public static final int AUGUST=7; - /** - * Field number for {@code get} and {@code set} indicating the - * week number within the current year. The first week of the year, as - * defined by {@code getFirstDayOfWeek()} and - * {@code getMinimalDaysInFirstWeek()}, has value 1. Subclasses - * define the value of {@code WEEK_OF_YEAR} for days before the first - * week of the year. - * - * @see #getFirstDayOfWeek - * @see #getMinimalDaysInFirstWeek - */ + /// Field number for `get` and `set` indicating the + /// week number within the current year. The first week of the year, as + /// defined by `getFirstDayOfWeek()` and + /// `getMinimalDaysInFirstWeek()`, has value 1. Subclasses + /// define the value of `WEEK_OF_YEAR` for days before the first + /// week of the year. + /// + /// #### See also + /// + /// - #getFirstDayOfWeek + /// + /// - #getMinimalDaysInFirstWeek public static final int WEEK_OF_YEAR = 3; - /** - * Field number for {@code get} and {@code set} indicating the - * week number within the current month. The first week of the month, as - * defined by {@code getFirstDayOfWeek()} and - * {@code getMinimalDaysInFirstWeek()}, has value 1. Subclasses - * define the value of {@code WEEK_OF_MONTH} for days before the - * first week of the month. - * - * @see #getFirstDayOfWeek - * @see #getMinimalDaysInFirstWeek - */ + /// Field number for `get` and `set` indicating the + /// week number within the current month. The first week of the month, as + /// defined by `getFirstDayOfWeek()` and + /// `getMinimalDaysInFirstWeek()`, has value 1. Subclasses + /// define the value of `WEEK_OF_MONTH` for days before the + /// first week of the month. + /// + /// #### See also + /// + /// - #getFirstDayOfWeek + /// + /// - #getMinimalDaysInFirstWeek public static final int WEEK_OF_MONTH = 4; - /** - * Field number for get and set indicating the day of the month. This is a synonym for DAY_OF_MONTH. - * See Also:DAY_OF_MONTH, Constant Field Values - */ + /// Field number for get and set indicating the day of the month. This is a synonym for DAY_OF_MONTH. + /// See Also:DAY_OF_MONTH, Constant Field Values public static final int DATE=5; - /** - * Field number for get and set indicating the day of the month. This is a synonym for DATE. - * See Also:DATE, Constant Field Values - */ + /// Field number for get and set indicating the day of the month. This is a synonym for DATE. + /// See Also:DATE, Constant Field Values public static final int DAY_OF_MONTH=5; - /** - * Field number for {@code get} and {@code set} indicating the - * day number within the current year. The first day of the year has value - * 1. - */ + /// Field number for `get` and `set` indicating the + /// day number within the current year. The first day of the year has value + /// 1. static final int DAY_OF_YEAR = 6; - /** - * Field number for get and set indicating the day of the week. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the day of the week. + /// See Also:Constant Field Values public static final int DAY_OF_WEEK=7; - /** - * Field number for {@code get} and {@code set} indicating the - * ordinal number of the day of the week within the current month. Together - * with the {@code DAY_OF_WEEK} field, this uniquely specifies a day - * within a month. Unlike {@code WEEK_OF_MONTH} and - * {@code WEEK_OF_YEAR}, this field's value does not - * depend on {@code getFirstDayOfWeek()} or - * {@code getMinimalDaysInFirstWeek()}. {@code DAY_OF_MONTH 1} - * through {@code 7} always correspond to DAY_OF_WEEK_IN_MONTH - * 1; - * {@code 8} through {@code 15} correspond to - * {@code DAY_OF_WEEK_IN_MONTH 2}, and so on. - * {@code DAY_OF_WEEK_IN_MONTH 0} indicates the week before - * {@code DAY_OF_WEEK_IN_MONTH 1}. Negative values count back from - * the end of the month, so the last Sunday of a month is specified as - * {@code DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1}. Because - * negative values count backward they will usually be aligned differently - * within the month than positive values. For example, if a month has 31 - * days, {@code DAY_OF_WEEK_IN_MONTH -1} will overlap - * {@code DAY_OF_WEEK_IN_MONTH 5} and the end of {@code 4}. - * - * @see #DAY_OF_WEEK - * @see #WEEK_OF_MONTH - */ + /// Field number for `get` and `set` indicating the + /// ordinal number of the day of the week within the current month. Together + /// with the `DAY_OF_WEEK` field, this uniquely specifies a day + /// within a month. Unlike `WEEK_OF_MONTH` and + /// `WEEK_OF_YEAR`, this field's value does *not* + /// depend on `getFirstDayOfWeek()` or + /// `getMinimalDaysInFirstWeek()`. `DAY_OF_MONTH 1` + /// through `7` always correspond to `DAY_OF_WEEK_IN_MONTH 1`; + /// `8` through `15` correspond to + /// `DAY_OF_WEEK_IN_MONTH 2`, and so on. + /// `DAY_OF_WEEK_IN_MONTH 0` indicates the week before + /// `DAY_OF_WEEK_IN_MONTH 1`. Negative values count back from + /// the end of the month, so the last Sunday of a month is specified as + /// `DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1`. Because + /// negative values count backward they will usually be aligned differently + /// within the month than positive values. For example, if a month has 31 + /// days, `DAY_OF_WEEK_IN_MONTH -1` will overlap + /// `DAY_OF_WEEK_IN_MONTH 5` and the end of `4`. + /// + /// #### See also + /// + /// - #DAY_OF_WEEK + /// + /// - #WEEK_OF_MONTH public static final int DAY_OF_WEEK_IN_MONTH = 8; - /** - * Value of the MONTH field indicating the twelfth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the twelfth month of the year. + /// See Also:Constant Field Values public static final int DECEMBER=11; - /** - * Value of the MONTH field indicating the second month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the second month of the year. + /// See Also:Constant Field Values public static final int FEBRUARY=1; - /** - * The field values for the currently set time for this calendar. - */ + /// The field values for the currently set time for this calendar. protected int[] fields; - /** - * Value of the DAY_OF_WEEK field indicating Friday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Friday. + /// See Also:Constant Field Values public static final int FRIDAY=6; - /** - * Field number for get and set indicating the hour of the morning or afternoon. HOUR is used for the 12-hour clock. E.g., at 10:04:15.250 PM the HOUR is 10. - * See Also:AM_PM, HOUR_OF_DAY, Constant Field Values - */ + /// Field number for get and set indicating the hour of the morning or afternoon. HOUR is used for the 12-hour clock. E.g., at 10:04:15.250 PM the HOUR is 10. + /// See Also:AM_PM, HOUR_OF_DAY, Constant Field Values public static final int HOUR=10; - /** - * Field number for get and set indicating the hour of the day. HOUR_OF_DAY is used for the 24-hour clock. E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the hour of the day. HOUR_OF_DAY is used for the 24-hour clock. E.g., at 10:04:15.250 PM the HOUR_OF_DAY is 22. + /// See Also:Constant Field Values public static final int HOUR_OF_DAY=11; - /** - * The flags which tell if a specified time field for the calendar is set. This is an array of FIELD_COUNT booleans, - */ + /// The flags which tell if a specified time field for the calendar is set. This is an array of FIELD_COUNT booleans, protected boolean[] isSet; - /** - * Value of the MONTH field indicating the first month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the first month of the year. + /// See Also:Constant Field Values public static final int JANUARY=0; - /** - * Value of the MONTH field indicating the seventh month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the seventh month of the year. + /// See Also:Constant Field Values public static final int JULY=6; - /** - * Value of the MONTH field indicating the sixth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the sixth month of the year. + /// See Also:Constant Field Values public static final int JUNE=5; - /** - * Value of the MONTH field indicating the third month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the third month of the year. + /// See Also:Constant Field Values public static final int MARCH=2; - /** - * Value of the MONTH field indicating the fifth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the fifth month of the year. + /// See Also:Constant Field Values public static final int MAY=4; - /** - * Field number for get and set indicating the millisecond within the second. E.g., at 10:04:15.250 PM the MILLISECOND is 250. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the millisecond within the second. E.g., at 10:04:15.250 PM the MILLISECOND is 250. + /// See Also:Constant Field Values public static final int MILLISECOND=14; - /** - * Field number for get and set indicating the minute within the hour. E.g., at 10:04:15.250 PM the MINUTE is 4. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the minute within the hour. E.g., at 10:04:15.250 PM the MINUTE is 4. + /// See Also:Constant Field Values public static final int MINUTE=12; - /** - * Value of the DAY_OF_WEEK field indicating Monday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Monday. + /// See Also:Constant Field Values public static final int MONDAY=2; - /** - * Field number for get and set indicating the month. This is a calendar-specific value. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the month. This is a calendar-specific value. + /// See Also:Constant Field Values public static final int MONTH=2; - /** - * Value of the MONTH field indicating the eleventh month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the eleventh month of the year. + /// See Also:Constant Field Values public static final int NOVEMBER=10; - /** - * Value of the MONTH field indicating the tenth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the tenth month of the year. + /// See Also:Constant Field Values public static final int OCTOBER=9; - /** - * Value of the AM_PM field indicating the period of the day from noon to just before midnight. - * See Also:Constant Field Values - */ + /// Value of the AM_PM field indicating the period of the day from noon to just before midnight. + /// See Also:Constant Field Values public static final int PM=1; - /** - * Value of the DAY_OF_WEEK field indicating Saturday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Saturday. + /// See Also:Constant Field Values public static final int SATURDAY=7; - /** - * Field number for get and set indicating the second within the minute. E.g., at 10:04:15.250 PM the SECOND is 15. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the second within the minute. E.g., at 10:04:15.250 PM the SECOND is 15. + /// See Also:Constant Field Values public static final int SECOND=13; - /** - * Value of the MONTH field indicating the ninth month of the year. - * See Also:Constant Field Values - */ + /// Value of the MONTH field indicating the ninth month of the year. + /// See Also:Constant Field Values public static final int SEPTEMBER=8; - /** - * Value of the DAY_OF_WEEK field indicating Sunday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Sunday. + /// See Also:Constant Field Values public static final int SUNDAY=1; - /** - * Value of the DAY_OF_WEEK field indicating Thursday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Thursday. + /// See Also:Constant Field Values public static final int THURSDAY=5; - /** - * The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT. - */ + /// The currently set time for this calendar, expressed in milliseconds after January 1, 1970, 0:00:00 GMT. protected long time; - /** - * Value of the DAY_OF_WEEK field indicating Tuesday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Tuesday. + /// See Also:Constant Field Values public static final int TUESDAY=3; - /** - * Value of the DAY_OF_WEEK field indicating Wednesday. - * See Also:Constant Field Values - */ + /// Value of the DAY_OF_WEEK field indicating Wednesday. + /// See Also:Constant Field Values public static final int WEDNESDAY=4; - /** - * Field number for get and set indicating the year. This is a calendar-specific value. - * See Also:Constant Field Values - */ + /// Field number for get and set indicating the year. This is a calendar-specific value. + /// See Also:Constant Field Values public static final int YEAR=1; - /** - * Constructs a Calendar with the default time zone. - * See Also:TimeZone.getDefault() - */ + /// Constructs a Calendar with the default time zone. + /// See Also:TimeZone.getDefault() protected Calendar(){ //TODO codavaj!! } - /** - * Compares the time field records. Equivalent to comparing result of conversion to UTC. - */ + /// Compares the time field records. Equivalent to comparing result of conversion to UTC. public boolean after(java.lang.Object when){ return false; //TODO codavaj!! } - /** - * Compares the time field records. Equivalent to comparing result of conversion to UTC. - */ + /// Compares the time field records. Equivalent to comparing result of conversion to UTC. public boolean before(java.lang.Object when){ return false; //TODO codavaj!! } - /** - * Converts the current millisecond time value time to field values in fields[]. This allows you to sync up the time field values with a new time that is set for the calendar. - */ + /// Converts the current millisecond time value time to field values in fields[]. This allows you to sync up the time field values with a new time that is set for the calendar. protected abstract void computeFields(); - /** - * Converts the current field values in fields[] to the millisecond time value time. - */ + /// Converts the current field values in fields[] to the millisecond time value time. protected abstract void computeTime(); - /** - * Compares this calendar to the specified object. The result is true if and only if the argument is not null and is a Calendar object that represents the same calendar as this object. - */ + /// Compares this calendar to the specified object. The result is true if and only if the argument is not null and is a Calendar object that represents the same calendar as this object. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Gets the value for a given time field. - */ + /// Gets the value for a given time field. public final int get(int field){ return 0; //TODO codavaj!! } - /** - * Gets a calendar using the default time zone. - */ + /// Gets a calendar using the default time zone. public static java.util.Calendar getInstance(){ return null; //TODO codavaj!! } - /** - * Gets a calendar using the specified time zone. - */ + /// Gets a calendar using the specified time zone. public static java.util.Calendar getInstance(java.util.TimeZone zone){ return null; //TODO codavaj!! } - /** - * Gets this Calendar's current time. - */ + /// Gets this Calendar's current time. public final java.util.Date getTime(){ return null; //TODO codavaj!! } - /** - * Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch). - */ + /// Gets this Calendar's current time as a long expressed in milliseconds after January 1, 1970, 0:00:00 GMT (the epoch). protected long getTimeInMillis(){ return 0l; //TODO codavaj!! } - /** - * Gets the time zone. - */ + /// Gets the time zone. public java.util.TimeZone getTimeZone(){ return null; //TODO codavaj!! } - /** - * Sets the time field with the given value. - */ + /// Sets the time field with the given value. public final void set(int field, int value){ return; //TODO codavaj!! } - /** - * Adds the specified amount to a {@code Calendar} field. - * - * @param field - * the {@code Calendar} field to modify. - * @param value - * the amount to add to the field. - * @throws IllegalArgumentException - * if {@code field} is {@code DST_OFFSET} or {@code - * ZONE_OFFSET}. - */ + /// Adds the specified amount to a `Calendar` field. + /// + /// #### Parameters + /// + /// - `field`: the `Calendar` field to modify. + /// + /// - `value`: the amount to add to the field. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `field` is `DST_OFFSET` or `ZONE_OFFSET`. public final void add(int field, int value) { } - /** - * Sets this Calendar's current time with the given Date. - * Note: Calling setTime() with Date(Long.MAX_VALUE) or Date(Long.MIN_VALUE) may yield incorrect field values from get(). - */ + /// Sets this Calendar's current time with the given Date. + /// Note: Calling setTime() with Date(Long.MAX_VALUE) or Date(Long.MIN_VALUE) may yield incorrect field values from get(). public final void setTime(java.util.Date date){ return; //TODO codavaj!! } - /** - * Sets this Calendar's current time from the given long value. - */ + /// Sets this Calendar's current time from the given long value. protected void setTimeInMillis(long millis){ return; //TODO codavaj!! } - /** - * Sets the time zone with the given time zone value. - */ + /// Sets the time zone with the given time zone value. public void setTimeZone(java.util.TimeZone value){ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/util/Collection.java b/Ports/CLDC11/src/java/util/Collection.java index 1297d21b50..55ac391203 100644 --- a/Ports/CLDC11/src/java/util/Collection.java +++ b/Ports/CLDC11/src/java/util/Collection.java @@ -18,299 +18,350 @@ package java.util; -/** - * {@code Collection} is the root of the collection hierarchy. It defines operations on - * data collections and the behavior that they will have in all implementations - * of {@code Collection}s. - * - * All direct or indirect implementations of {@code Collection} should implement at - * least two constructors. One with no parameters which creates an empty - * collection and one with a parameter of type {@code Collection}. This second - * constructor can be used to create a collection of different type as the - * initial collection but with the same elements. Implementations of {@code Collection} - * cannot be forced to implement these two constructors but at least all - * implementations under {@code java.util} do. - * - * Methods that change the content of a collection throw an - * {@code UnsupportedOperationException} if the underlying collection does not - * support that operation, though it's not mandatory to throw such an {@code Exception} - * in cases where the requested operation would not change the collection. In - * these cases it's up to the implementation whether it throws an - * {@code UnsupportedOperationException} or not. - * - * Methods marked with (optional) can throw an - * {@code UnsupportedOperationException} if the underlying collection doesn't - * support that method. - */ +/// `Collection` is the root of the collection hierarchy. It defines operations on +/// data collections and the behavior that they will have in all implementations +/// of `Collection`s. +/// +/// All direct or indirect implementations of `Collection` should implement at +/// least two constructors. One with no parameters which creates an empty +/// collection and one with a parameter of type `Collection`. This second +/// constructor can be used to create a collection of different type as the +/// initial collection but with the same elements. Implementations of `Collection` +/// cannot be forced to implement these two constructors but at least all +/// implementations under `java.util` do. +/// +/// Methods that change the content of a collection throw an +/// `UnsupportedOperationException` if the underlying collection does not +/// support that operation, though it's not mandatory to throw such an `Exception` +/// in cases where the requested operation would not change the collection. In +/// these cases it's up to the implementation whether it throws an +/// `UnsupportedOperationException` or not. +/// +/// Methods marked with (optional) can throw an +/// `UnsupportedOperationException` if the underlying collection doesn't +/// support that method. public interface Collection extends java.lang.Iterable { - /** - * Attempts to add {@code object} to the contents of this - * {@code Collection} (optional). - * - * After this method finishes successfully it is guaranteed that the object - * is contained in the collection. - * - * If the collection was modified it returns {@code true}, {@code false} if - * no changes were made. - * - * An implementation of {@code Collection} may narrow the set of accepted - * objects, but it has to specify this in the documentation. If the object - * to be added does not meet this restriction, then an - * {@code IllegalArgumentException} is thrown. - * - * If a collection does not yet contain an object that is to be added and - * adding the object fails, this method must throw an appropriate - * unchecked Exception. Returning false is not permitted in this case - * because it would violate the postcondition that the element will be part - * of the collection after this method finishes. - * - * @param object - * the object to add. - * @return {@code true} if this {@code Collection} is - * modified, {@code false} otherwise. - * - * @throws UnsupportedOperationException - * if adding to this {@code Collection} is not supported. - * @throws ClassCastException - * if the class of the object is inappropriate for this - * collection. - * @throws IllegalArgumentException - * if the object cannot be added to this {@code Collection}. - * @throws NullPointerException - * if null elements cannot be added to the {@code Collection}. - */ + /// Attempts to add `object` to the contents of this + /// `Collection` (optional). + /// + /// After this method finishes successfully it is guaranteed that the object + /// is contained in the collection. + /// + /// If the collection was modified it returns `true`, `false` if + /// no changes were made. + /// + /// An implementation of `Collection` may narrow the set of accepted + /// objects, but it has to specify this in the documentation. If the object + /// to be added does not meet this restriction, then an + /// `IllegalArgumentException` is thrown. + /// + /// If a collection does not yet contain an object that is to be added and + /// adding the object fails, this method *must* throw an appropriate + /// unchecked Exception. Returning false is not permitted in this case + /// because it would violate the postcondition that the element will be part + /// of the collection after this method finishes. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is + /// modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the object is inappropriate for this + /// collection. + /// + /// - `IllegalArgumentException`: if the object cannot be added to this `Collection`. + /// + /// - `NullPointerException`: if null elements cannot be added to the `Collection`. public boolean add(E object); - /** - * Attempts to add all of the objects contained in {@code Collection} - * to the contents of this {@code Collection} (optional). If the passed {@code Collection} - * is changed during the process of adding elements to this {@code Collection}, the - * behavior is not defined. - * - * @param collection - * the {@code Collection} of objects. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if adding to this {@code Collection} is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this - * {@code Collection}. - * @throws IllegalArgumentException - * if an object cannot be added to this {@code Collection}. - * @throws NullPointerException - * if {@code collection} is {@code null}, or if it - * contains {@code null} elements and this {@code Collection} does - * not support such elements. - */ + /// Attempts to add all of the objects contained in `Collection` + /// to the contents of this `Collection` (optional). If the passed `Collection` + /// is changed during the process of adding elements to this `Collection`, the + /// behavior is not defined. + /// + /// #### Parameters + /// + /// - `collection`: the `Collection` of objects. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of an object is inappropriate for this + /// `Collection`. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this `Collection`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` is `null`, or if it + /// contains `null` elements and this `Collection` does + /// not support such elements. public boolean addAll(Collection collection); - /** - * Removes all elements from this {@code Collection}, leaving it empty (optional). - * - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `Collection`, leaving it empty (optional). + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size public void clear(); - /** - * Tests whether this {@code Collection} contains the specified object. Returns - * {@code true} if and only if at least one element {@code elem} in this - * {@code Collection} meets following requirement: - * {@code (object==null ? elem==null : object.equals(elem))}. - * - * @param object - * the object to search for. - * @return {@code true} if object is an element of this {@code Collection}, - * {@code false} otherwise. - * @throws ClassCastException - * if the object to look for isn't of the correct - * type. - * @throws NullPointerException - * if the object to look for is {@code null} and this - * {@code Collection} doesn't support {@code null} elements. - */ + /// Tests whether this `Collection` contains the specified object. Returns + /// `true` if and only if at least one element `elem` in this + /// `Collection` meets following requirement: + /// `(object==null ? elem==null : object.equals(elem))`. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if object is an element of this `Collection`, + /// `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the object to look for isn't of the correct + /// type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the object to look for is `null` and this + /// `Collection` doesn't support `null` elements. public boolean contains(Object object); - /** - * Tests whether this {@code Collection} contains all objects contained in the - * specified {@code Collection}. If an element {@code elem} is contained several - * times in the specified {@code Collection}, the method returns {@code true} even - * if {@code elem} is contained only once in this {@code Collection}. - * - * @param collection - * the collection of objects. - * @return {@code true} if all objects in the specified {@code Collection} are - * elements of this {@code Collection}, {@code false} otherwise. - * @throws ClassCastException - * if one or more elements of {@code collection} isn't of the - * correct type. - * @throws NullPointerException - * if {@code collection} contains at least one {@code null} - * element and this {@code Collection} doesn't support {@code null} - * elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Tests whether this `Collection` contains all objects contained in the + /// specified `Collection`. If an element `elem` is contained several + /// times in the specified `Collection`, the method returns `true` even + /// if `elem` is contained only once in this `Collection`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if all objects in the specified `Collection` are + /// elements of this `Collection`, `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` isn't of the + /// correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one `null` + /// element and this `Collection` doesn't support `null` + /// elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean containsAll(Collection collection); - /** - * Compares the argument to the receiver, and returns true if they represent - * the same object using a class specific comparison. - * - * @param object - * the object to compare with this object. - * @return {@code true} if the object is the same as this object and - * {@code false} if it is different from this object. - * @see #hashCode - */ + /// Compares the argument to the receiver, and returns true if they represent + /// the *same* object using a class specific comparison. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object. + /// + /// #### Returns + /// + /// @return `true` if the object is the same as this object and + /// `false` if it is different from this object. + /// + /// #### See also + /// + /// - #hashCode public boolean equals(Object object); - /** - * Returns an integer hash code for the receiver. Objects which are equal - * return the same value for this method. - * - * @return the receiver's hash. - * - * @see #equals - */ + /// Returns an integer hash code for the receiver. Objects which are equal + /// return the same value for this method. + /// + /// #### Returns + /// + /// the receiver's hash. + /// + /// #### See also + /// + /// - #equals public int hashCode(); - /** - * Returns if this {@code Collection} contains no elements. - * - * @return {@code true} if this {@code Collection} has no elements, {@code false} - * otherwise. - * - * @see #size - */ + /// Returns if this `Collection` contains no elements. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size public boolean isEmpty(); - /** - * Returns an instance of {@link Iterator} that may be used to access the - * objects contained by this {@code Collection}. The order in which the elements are - * returned by the iterator is not defined. Only if the instance of the - * {@code Collection} has a defined order the elements are returned in that order. - * - * @return an iterator for accessing the {@code Collection} contents. - */ + /// Returns an instance of `Iterator` that may be used to access the + /// objects contained by this `Collection`. The order in which the elements are + /// returned by the iterator is not defined. Only if the instance of the + /// `Collection` has a defined order the elements are returned in that order. + /// + /// #### Returns + /// + /// an iterator for accessing the `Collection` contents. public Iterator iterator(); - /** - * Removes one instance of the specified object from this {@code Collection} if one - * is contained (optional). The element {@code elem} that is removed - * complies with {@code (object==null ? elem==null : object.equals(elem)}. - * - * @param object - * the object to remove. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if the object passed is not of the correct type. - * @throws NullPointerException - * if {@code object} is {@code null} and this {@code Collection} - * doesn't support {@code null} elements. - */ + /// Removes one instance of the specified object from this `Collection` if one + /// is contained (optional). The element `elem` that is removed + /// complies with `(object==null ? elem==null : object.equals(elem)`. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: if the object passed is not of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `object` is `null` and this `Collection` + /// doesn't support `null` elements. public boolean remove(Object object); - /** - * Removes all occurrences in this {@code Collection} of each object in the - * specified {@code Collection} (optional). After this method returns none of the - * elements in the passed {@code Collection} can be found in this {@code Collection} - * anymore. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if one or more elements of {@code collection} - * isn't of the correct type. - * @throws NullPointerException - * if {@code collection} contains at least one - * {@code null} element and this {@code Collection} doesn't support - * {@code null} elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Removes all occurrences in this `Collection` of each object in the + /// specified `Collection` (optional). After this method returns none of the + /// elements in the passed `Collection` can be found in this `Collection` + /// anymore. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` + /// isn't of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one + /// `null` element and this `Collection` doesn't support + /// `null` elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean removeAll(Collection collection); - /** - * Removes all objects from this {@code Collection} that are not also found in the - * {@code Collection} passed (optional). After this method returns this {@code Collection} - * will only contain elements that also can be found in the {@code Collection} - * passed to this method. - * - * @param collection - * the collection of objects to retain. - * @return {@code true} if this {@code Collection} is modified, {@code false} - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code Collection} is not supported. - * @throws ClassCastException - * if one or more elements of {@code collection} - * isn't of the correct type. - * @throws NullPointerException - * if {@code collection} contains at least one - * {@code null} element and this {@code Collection} doesn't support - * {@code null} elements. - * @throws NullPointerException - * if {@code collection} is {@code null}. - */ + /// Removes all objects from this `Collection` that are not also found in the + /// `Collection` passed (optional). After this method returns this `Collection` + /// will only contain elements that also can be found in the `Collection` + /// passed to this method. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to retain. + /// + /// #### Returns + /// + /// @return `true` if this `Collection` is modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Collection` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if one or more elements of `collection` + /// isn't of the correct type. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if `collection` contains at least one + /// `null` element and this `Collection` doesn't support + /// `null` elements. + /// + /// - `NullPointerException`: if `collection` is `null`. public boolean retainAll(Collection collection); - /** - * Returns a count of how many objects this {@code Collection} contains. - * - * @return how many objects this {@code Collection} contains, or Integer.MAX_VALUE - * if there are more than Integer.MAX_VALUE elements in this - * {@code Collection}. - */ + /// Returns a count of how many objects this `Collection` contains. + /// + /// #### Returns + /// + /// @return how many objects this `Collection` contains, or Integer.MAX_VALUE + /// if there are more than Integer.MAX_VALUE elements in this + /// `Collection`. public int size(); - /** - * Returns a new array containing all elements contained in this {@code Collection}. - * - * If the implementation has ordered elements it will return the element - * array in the same order as an iterator would return them. - * - * The array returned does not reflect any changes of the {@code Collection}. A new - * array is created even if the underlying data structure is already an - * array. - * - * @return an array of the elements from this {@code Collection}. - */ + /// Returns a new array containing all elements contained in this `Collection`. + /// + /// If the implementation has ordered elements it will return the element + /// array in the same order as an iterator would return them. + /// + /// The array returned does not reflect any changes of the `Collection`. A new + /// array is created even if the underlying data structure is already an + /// array. + /// + /// #### Returns + /// + /// an array of the elements from this `Collection`. public Object[] toArray(); - /** - * Returns an array containing all elements contained in this {@code Collection}. If - * the specified array is large enough to hold the elements, the specified - * array is used, otherwise an array of the same type is created. If the - * specified array is used and is larger than this {@code Collection}, the array - * element following the {@code Collection} elements is set to null. - * - * If the implementation has ordered elements it will return the element - * array in the same order as an iterator would return them. - * - * {@code toArray(new Object[0])} behaves exactly the same way as - * {@code toArray()} does. - * - * @param array - * the array. - * @return an array of the elements from this {@code Collection}. - * - * @throws ArrayStoreException - * if the type of an element in this {@code Collection} cannot be - * stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this `Collection`. If + /// the specified array is large enough to hold the elements, the specified + /// array is used, otherwise an array of the same type is created. If the + /// specified array is used and is larger than this `Collection`, the array + /// element following the `Collection` elements is set to null. + /// + /// If the implementation has ordered elements it will return the element + /// array in the same order as an iterator would return them. + /// + /// `toArray(new Object[0])` behaves exactly the same way as + /// `toArray()` does. + /// + /// #### Parameters + /// + /// - `array`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `Collection`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// if the type of an element in this `Collection` cannot be + /// stored in the type of the specified array. public T[] toArray(T[] array); } diff --git a/Ports/CLDC11/src/java/util/Collections.java b/Ports/CLDC11/src/java/util/Collections.java index 4ce54e4262..932ed72909 100644 --- a/Ports/CLDC11/src/java/util/Collections.java +++ b/Ports/CLDC11/src/java/util/Collections.java @@ -18,12 +18,12 @@ package java.util; -/** - * {@code Collections} contains static methods which operate on - * {@code Collection} classes. - * - * @since 1.2 - */ +/// `Collections` contains static methods which operate on +/// `Collection` classes. +/// +/// #### Since +/// +/// 1.2 public class Collections { private static final class CopiesList extends AbstractList { @@ -158,27 +158,19 @@ private Object readResolve() { } } - /** - * An empty immutable instance of {@link List}. - */ + /// An empty immutable instance of `List`. @SuppressWarnings("unchecked") public static final List EMPTY_LIST = new EmptyList(); - /** - * An empty immutable instance of {@link Set}. - */ + /// An empty immutable instance of `Set`. @SuppressWarnings("unchecked") public static final Set EMPTY_SET = new EmptySet(); - /** - * An empty immutable instance of {@link Map}. - */ + /// An empty immutable instance of `Map`. @SuppressWarnings("unchecked") public static final Map EMPTY_MAP = new EmptyMap(); - /** - * This class is a singleton so that equals() and hashCode() work properly. - */ + /// This class is a singleton so that equals() and hashCode() work properly. private static final class ReverseComparator implements Comparator { private static final ReverseComparator INSTANCE @@ -492,17 +484,18 @@ public List subList(int start, int end) { } } - /** - * Replaces this SynchronizedRandomAccessList with a SynchronizedList so - * that JREs before 1.4 can deserialize this object without any - * problems. This is necessary since RandomAccess API was introduced - * only in 1.4. - *

- * - * @return SynchronizedList - * - * @see SynchronizedList#readResolve() - */ + /// Replaces this SynchronizedRandomAccessList with a SynchronizedList so + /// that JREs before 1.4 can deserialize this object without any + /// problems. This is necessary since RandomAccess API was introduced + /// only in 1.4. + /// + /// #### Returns + /// + /// SynchronizedList + /// + /// #### See also + /// + /// - SynchronizedList#readResolve() private Object writeReplace() { return new SynchronizedList(list); } @@ -634,20 +627,21 @@ public List subList(int start, int end) { } } - /** - * Resolves SynchronizedList instances to SynchronizedRandomAccessList - * instances if the underlying list is a Random Access list. - *

- * This is necessary since SynchronizedRandomAccessList instances are - * replaced with SynchronizedList instances during serialization for - * compliance with JREs before 1.4. - *

- * - * @return a SynchronizedList instance if the underlying list implements - * RandomAccess interface, or this same object if not. - * - * @see SynchronizedRandomAccessList#writeReplace() - */ + /// Resolves SynchronizedList instances to SynchronizedRandomAccessList + /// instances if the underlying list is a Random Access list. + /// + /// This is necessary since SynchronizedRandomAccessList instances are + /// replaced with SynchronizedList instances during serialization for + /// compliance with JREs before 1.4. + /// + /// #### Returns + /// + /// @return a SynchronizedList instance if the underlying list implements + /// RandomAccess interface, or this same object if not. + /// + /// #### See also + /// + /// - SynchronizedRandomAccessList#writeReplace() private Object readResolve() { if (list instanceof RandomAccess) { return new SynchronizedRandomAccessList(list, mutex); @@ -992,17 +986,18 @@ public List subList(int start, int end) { return new UnmodifiableRandomAccessList(list.subList(start, end)); } - /** - * Replaces this UnmodifiableRandomAccessList with an UnmodifiableList - * so that JREs before 1.4 can deserialize this object without any - * problems. This is necessary since RandomAccess API was introduced - * only in 1.4. - *

- * - * @return UnmodifiableList - * - * @see UnmodifiableList#readResolve() - */ + /// Replaces this UnmodifiableRandomAccessList with an UnmodifiableList + /// so that JREs before 1.4 can deserialize this object without any + /// problems. This is necessary since RandomAccess API was introduced + /// only in 1.4. + /// + /// #### Returns + /// + /// UnmodifiableList + /// + /// #### See also + /// + /// - UnmodifiableList#readResolve() private Object writeReplace() { return new UnmodifiableList(list); } @@ -1105,21 +1100,22 @@ public List subList(int start, int end) { return new UnmodifiableList(list.subList(start, end)); } - /** - * Resolves UnmodifiableList instances to UnmodifiableRandomAccessList - * instances if the underlying list is a Random Access list. - *

- * This is necessary since UnmodifiableRandomAccessList instances are - * replaced with UnmodifiableList instances during serialization for - * compliance with JREs before 1.4. - *

- * - * @return an UnmodifiableList instance if the underlying list - * implements RandomAccess interface, or this same object if - * not. - * - * @see UnmodifiableRandomAccessList#writeReplace() - */ + /// Resolves UnmodifiableList instances to UnmodifiableRandomAccessList + /// instances if the underlying list is a Random Access list. + /// + /// This is necessary since UnmodifiableRandomAccessList instances are + /// replaced with UnmodifiableList instances during serialization for + /// compliance with JREs before 1.4. + /// + /// #### Returns + /// + /// @return an UnmodifiableList instance if the underlying list + /// implements RandomAccess interface, or this same object if + /// not. + /// + /// #### See also + /// + /// - UnmodifiableRandomAccessList#writeReplace() private Object readResolve() { if (list instanceof RandomAccess) { return new UnmodifiableRandomAccessList(list); @@ -1387,23 +1383,28 @@ private Collections() { /* empty */ } - /** - * Performs a binary search for the specified element in the specified - * sorted list. The list needs to be already sorted in natural sorting - * order. Searching in an unsorted array has an undefined result. It's also - * undefined which element is found if there are multiple occurrences of the - * same element. - * - * @param list - * the sorted list to search. - * @param object - * the element to find. - * @return the non-negative index of the element, or a negative index which - * is the {@code -index - 1} where the element would be inserted - * @throws ClassCastException - * if an element in the List or the search element does not - * implement Comparable, or cannot be compared to each other. - */ + /// Performs a binary search for the specified element in the specified + /// sorted list. The list needs to be already sorted in natural sorting + /// order. Searching in an unsorted array has an undefined result. It's also + /// undefined which element is found if there are multiple occurrences of the + /// same element. + /// + /// #### Parameters + /// + /// - `list`: the sorted list to search. + /// + /// - `object`: the element to find. + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the `-index - 1` where the element would be inserted + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if an element in the List or the search element does not + /// implement Comparable, or cannot be compared to each other. @SuppressWarnings("unchecked") public static int binarySearch( List> list, T object) { @@ -1443,27 +1444,34 @@ public static int binarySearch( return -mid - (result < 0 ? 1 : 2); } - /** - * Performs a binary search for the specified element in the specified - * sorted list using the specified comparator. The list needs to be already - * sorted according to the comparator passed. Searching in an unsorted array - * has an undefined result. It's also undefined which element is found if - * there are multiple occurrences of the same element. - * - * @param The element type - * @param list - * the sorted List to search. - * @param object - * the element to find. - * @param comparator - * the comparator. If the comparator is {@code null} then the - * search uses the objects' natural ordering. - * @return the non-negative index of the element, or a negative index which - * is the {@code -index - 1} where the element would be inserted. - * @throws ClassCastException - * when an element in the list and the searched element cannot - * be compared to each other using the comparator. - */ + /// Performs a binary search for the specified element in the specified + /// sorted list using the specified comparator. The list needs to be already + /// sorted according to the comparator passed. Searching in an unsorted array + /// has an undefined result. It's also undefined which element is found if + /// there are multiple occurrences of the same element. + /// + /// #### Parameters + /// + /// - `The`: element type + /// + /// - `list`: the sorted List to search. + /// + /// - `object`: the element to find. + /// + /// - `comparator`: @param comparator + /// the comparator. If the comparator is `null` then the + /// search uses the objects' natural ordering. + /// + /// #### Returns + /// + /// @return the non-negative index of the element, or a negative index which + /// is the `-index - 1` where the element would be inserted. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the list and the searched element cannot + /// be compared to each other using the comparator. @SuppressWarnings("unchecked") public static int binarySearch(List list, T object, Comparator comparator) { @@ -1499,22 +1507,24 @@ public static int binarySearch(List list, T object, return -mid - (result < 0 ? 1 : 2); } - /** - * Copies the elements from the source list to the destination list. At the - * end both lists will have the same objects at the same index. If the - * destination array is larger than the source list, the elements in the - * destination list with {@code index >= source.size()} will be unchanged. - * - * @param destination - * the list whose elements are set from the source list. - * @param source - * the list with the elements to be copied into the destination. - * @throws IndexOutOfBoundsException - * when the destination list is smaller than the source list. - * @throws UnsupportedOperationException - * when replacing an element in the destination list is not - * supported. - */ + /// Copies the elements from the source list to the destination list. At the + /// end both lists will have the same objects at the same index. If the + /// destination array is larger than the source list, the elements in the + /// destination list with `index >= source.size()` will be unchanged. + /// + /// #### Parameters + /// + /// - `destination`: the list whose elements are set from the source list. + /// + /// - `source`: the list with the elements to be copied into the destination. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: when the destination list is smaller than the source list. + /// + /// - `UnsupportedOperationException`: @throws UnsupportedOperationException + /// when replacing an element in the destination list is not + /// supported. public static void copy(List destination, List source) { if (destination.size() < source.size()) { @@ -1534,13 +1544,15 @@ public static void copy(List destination, } } - /** - * Returns an {@code Enumeration} on the specified collection. - * - * @param collection - * the collection to enumerate. - * @return an Enumeration. - */ + /// Returns an `Enumeration` on the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection to enumerate. + /// + /// #### Returns + /// + /// an Enumeration. public static java.util.Enumeration enumeration(Collection collection) { final Collection c = collection; return new java.util.Enumeration() { @@ -1556,16 +1568,17 @@ public T nextElement() { }; } - /** - * Fills the specified list with the specified element. - * - * @param list - * the list to fill. - * @param object - * the element to fill the list with. - * @throws UnsupportedOperationException - * when replacing an element in the List is not supported. - */ + /// Fills the specified list with the specified element. + /// + /// #### Parameters + /// + /// - `list`: the list to fill. + /// + /// - `object`: the element to fill the list with. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when replacing an element in the List is not supported. public static void fill(List list, T object) { ListIterator it = list.listIterator(); while (it.hasNext()) { @@ -1574,17 +1587,22 @@ public static void fill(List list, T object) { } } - /** - * Searches the specified collection for the maximum element. - * - * @param collection - * the collection to search. - * @return the maximum element in the Collection. - * @throws ClassCastException - * when an element in the collection does not implement - * {@code Comparable} or elements cannot be compared to each - * other. - */ + /// Searches the specified collection for the maximum element. + /// + /// #### Parameters + /// + /// - `collection`: the collection to search. + /// + /// #### Returns + /// + /// the maximum element in the Collection. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the collection does not implement + /// `Comparable` or elements cannot be compared to each + /// other. public static > T max( Collection collection) { Iterator it = collection.iterator(); @@ -1598,19 +1616,24 @@ public static > T max( return max; } - /** - * Searches the specified collection for the maximum element using the - * specified comparator. - * - * @param collection - * the collection to search. - * @param comparator - * the comparator. - * @return the maximum element in the Collection. - * @throws ClassCastException - * when elements in the collection cannot be compared to each - * other using the {@code Comparator}. - */ + /// Searches the specified collection for the maximum element using the + /// specified comparator. + /// + /// #### Parameters + /// + /// - `collection`: the collection to search. + /// + /// - `comparator`: the comparator. + /// + /// #### Returns + /// + /// the maximum element in the Collection. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when elements in the collection cannot be compared to each + /// other using the `Comparator`. public static T max(Collection collection, Comparator comparator) { if (comparator == null) { @@ -1630,17 +1653,22 @@ public static T max(Collection collection, return max; } - /** - * Searches the specified collection for the minimum element. - * - * @param collection - * the collection to search. - * @return the minimum element in the collection. - * @throws ClassCastException - * when an element in the collection does not implement - * {@code Comparable} or elements cannot be compared to each - * other. - */ + /// Searches the specified collection for the minimum element. + /// + /// #### Parameters + /// + /// - `collection`: the collection to search. + /// + /// #### Returns + /// + /// the minimum element in the collection. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the collection does not implement + /// `Comparable` or elements cannot be compared to each + /// other. public static > T min( Collection collection) { Iterator it = collection.iterator(); @@ -1654,19 +1682,24 @@ public static > T min( return min; } - /** - * Searches the specified collection for the minimum element using the - * specified comparator. - * - * @param collection - * the collection to search. - * @param comparator - * the comparator. - * @return the minimum element in the collection. - * @throws ClassCastException - * when elements in the collection cannot be compared to each - * other using the {@code Comparator}. - */ + /// Searches the specified collection for the minimum element using the + /// specified comparator. + /// + /// #### Parameters + /// + /// - `collection`: the collection to search. + /// + /// - `comparator`: the comparator. + /// + /// #### Returns + /// + /// the minimum element in the collection. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when elements in the collection cannot be compared to each + /// other using the `Comparator`. public static T min(Collection collection, Comparator comparator) { if (comparator == null) { @@ -1686,31 +1719,36 @@ public static T min(Collection collection, return min; } - /** - * Returns a list containing the specified number of the specified element. - * The list cannot be modified. The list is serializable. - * - * @param length - * the size of the returned list. - * @param object - * the element to be added {@code length} times to a list. - * @return a list containing {@code length} copies of the element. - * @throws IllegalArgumentException - * when {@code length < 0}. - */ + /// Returns a list containing the specified number of the specified element. + /// The list cannot be modified. The list is serializable. + /// + /// #### Parameters + /// + /// - `length`: the size of the returned list. + /// + /// - `object`: the element to be added `length` times to a list. + /// + /// #### Returns + /// + /// a list containing `length` copies of the element. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: when `length < 0`. public static List nCopies(final int length, T object) { return new CopiesList(length, object); } - /** - * Modifies the specified {@code List} by reversing the order of the - * elements. - * - * @param list - * the list to reverse. - * @throws UnsupportedOperationException - * when replacing an element in the List is not supported. - */ + /// Modifies the specified `List` by reversing the order of the + /// elements. + /// + /// #### Parameters + /// + /// - `list`: the list to reverse. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when replacing an element in the List is not supported. @SuppressWarnings("unchecked") public static void reverse(List list) { int size = list.size(); @@ -1725,34 +1763,47 @@ public static void reverse(List list) { } } - /** - * A comparator which reverses the natural order of the elements. The - * {@code Comparator} that's returned is {@link Serializable}. - * - * @return a {@code Comparator} instance. - * @see Comparator - * @see Comparable - * @see Serializable - */ + /// A comparator which reverses the natural order of the elements. The + /// `Comparator` that's returned is `Serializable`. + /// + /// #### Returns + /// + /// a `Comparator` instance. + /// + /// #### See also + /// + /// - Comparator + /// + /// - Comparable + /// + /// - Serializable @SuppressWarnings("unchecked") public static Comparator reverseOrder() { return (Comparator) ReverseComparator.INSTANCE; } - /** - * Returns a {@link Comparator} that reverses the order of the - * {@code Comparator} passed. If the {@code Comparator} passed is - * {@code null}, then this method is equivalent to {@link #reverseOrder()}. - *

- * The {@code Comparator} that's returned is {@link Serializable} if the - * {@code Comparator} passed is serializable or {@code null}. - * - * @param c - * the {@code Comparator} to reverse or {@code null}. - * @return a {@code Comparator} instance. - * @see Comparator - * @since 1.5 - */ + /// Returns a `Comparator` that reverses the order of the + /// `Comparator` passed. If the `Comparator` passed is + /// `null`, then this method is equivalent to `#reverseOrder()`. + /// + /// The `Comparator` that's returned is `Serializable` if the + /// `Comparator` passed is serializable or `null`. + /// + /// #### Parameters + /// + /// - `c`: the `Comparator` to reverse or `null`. + /// + /// #### Returns + /// + /// a `Comparator` instance. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - Comparator public static Comparator reverseOrder(Comparator c) { if (c == null) { return reverseOrder(); @@ -1763,30 +1814,31 @@ public static Comparator reverseOrder(Comparator c) { return new ReverseComparatorWithComparator(c); } - /** - * Moves every element of the list to a random new position in the list. - * - * @param list - * the List to shuffle. - * - * @throws UnsupportedOperationException - * when replacing an element in the List is not supported. - */ + /// Moves every element of the list to a random new position in the list. + /// + /// #### Parameters + /// + /// - `list`: the List to shuffle. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when replacing an element in the List is not supported. public static void shuffle(List list) { shuffle(list, new java.util.Random()); } - /** - * Moves every element of the list to a random new position in the list - * using the specified random number generator. - * - * @param list - * the list to shuffle. - * @param random - * the random number generator. - * @throws UnsupportedOperationException - * when replacing an element in the list is not supported. - */ + /// Moves every element of the list to a random new position in the list + /// using the specified random number generator. + /// + /// #### Parameters + /// + /// - `list`: the list to shuffle. + /// + /// - `random`: the random number generator. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when replacing an element in the list is not supported. public static void shuffle(List list, java.util.Random random) { @SuppressWarnings("unchecked") // we won't put foreign objects in final List objectList = (List) list; @@ -1814,54 +1866,62 @@ public static void shuffle(List list, java.util.Random random) { } } - /** - * Returns a set containing the specified element. The set cannot be - * modified. The set is serializable. - * - * @param object - * the element. - * @return a set containing the element. - */ + /// Returns a set containing the specified element. The set cannot be + /// modified. The set is serializable. + /// + /// #### Parameters + /// + /// - `object`: the element. + /// + /// #### Returns + /// + /// a set containing the element. public static Set singleton(E object) { return new SingletonSet(object); } - /** - * Returns a list containing the specified element. The list cannot be - * modified. The list is serializable. - * - * @param object - * the element. - * @return a list containing the element. - */ + /// Returns a list containing the specified element. The list cannot be + /// modified. The list is serializable. + /// + /// #### Parameters + /// + /// - `object`: the element. + /// + /// #### Returns + /// + /// a list containing the element. public static List singletonList(E object) { return new SingletonList(object); } - /** - * Returns a Map containing the specified key and value. The map cannot be - * modified. The map is serializable. - * - * @param key - * the key. - * @param value - * the value. - * @return a Map containing the key and value. - */ + /// Returns a Map containing the specified key and value. The map cannot be + /// modified. The map is serializable. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// a Map containing the key and value. public static Map singletonMap(K key, V value) { return new SingletonMap(key, value); } - /** - * Sorts the specified list in ascending natural order. The algorithm is - * stable which means equal elements don't get reordered. - * - * @param list - * the list to be sorted. - * @throws ClassCastException - * when an element in the List does not implement Comparable or - * elements cannot be compared to each other. - */ + /// Sorts the specified list in ascending natural order. The algorithm is + /// stable which means equal elements don't get reordered. + /// + /// #### Parameters + /// + /// - `list`: the list to be sorted. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the List does not implement Comparable or + /// elements cannot be compared to each other. @SuppressWarnings("unchecked") public static > void sort(List list) { Object[] array = list.toArray(); @@ -1874,18 +1934,20 @@ public static > void sort(List list } } - /** - * Sorts the specified list using the specified comparator. The algorithm is - * stable which means equal elements don't get reordered. - * - * @param list - * the list to be sorted. - * @param comparator - * the comparator. - * @throws ClassCastException - * when elements in the list cannot be compared to each other - * using the comparator. - */ + /// Sorts the specified list using the specified comparator. The algorithm is + /// stable which means equal elements don't get reordered. + /// + /// #### Parameters + /// + /// - `list`: the list to be sorted. + /// + /// - `comparator`: the comparator. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when elements in the list cannot be compared to each other + /// using the comparator. @SuppressWarnings("unchecked") public static void sort(List list, Comparator comparator) { T[] array = list.toArray((T[]) new Object[list.size()]); @@ -1898,22 +1960,26 @@ public static void sort(List list, Comparator comparator) { } } - /** - * Swaps the elements of list {@code list} at indices {@code index1} and - * {@code index2}. - * - * @param list - * the list to manipulate. - * @param index1 - * position of the first element to swap with the element in - * index2. - * @param index2 - * position of the other element. - * - * @throws IndexOutOfBoundsException - * if index1 or index2 is out of range of this list. - * @since 1.4 - */ + /// Swaps the elements of list `list` at indices `index1` and + /// `index2`. + /// + /// #### Parameters + /// + /// - `list`: the list to manipulate. + /// + /// - `index1`: @param index1 + /// position of the first element to swap with the element in + /// index2. + /// + /// - `index2`: position of the other element. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if index1 or index2 is out of range of this list. + /// + /// #### Since + /// + /// 1.4 @SuppressWarnings("unchecked") public static void swap(List list, int index1, int index2) { if (list == null) { @@ -1930,23 +1996,28 @@ public static void swap(List list, int index1, int index2) { rawList.set(index2, rawList.set(index1, rawList.get(index2))); } - /** - * Replaces all occurrences of Object {@code obj} in {@code list} with - * {@code newObj}. If the {@code obj} is {@code null}, then all - * occurrences of {@code null} are replaced with {@code newObj}. - * - * @param list - * the list to modify. - * @param obj - * the object to find and replace occurrences of. - * @param obj2 - * the object to replace all occurrences of {@code obj} in - * {@code list}. - * @return true, if at least one occurrence of {@code obj} has been found in - * {@code list}. - * @throws UnsupportedOperationException - * if the list does not support setting elements. - */ + /// Replaces all occurrences of Object `obj` in `list` with + /// `newObj`. If the `obj` is `null`, then all + /// occurrences of `null` are replaced with `newObj`. + /// + /// #### Parameters + /// + /// - `list`: the list to modify. + /// + /// - `obj`: the object to find and replace occurrences of. + /// + /// - `obj2`: @param obj2 + /// the object to replace all occurrences of `obj` in + /// `list`. + /// + /// #### Returns + /// + /// @return true, if at least one occurrence of `obj` has been found in + /// `list`. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if the list does not support setting elements. public static boolean replaceAll(List list, T obj, T obj2) { int index; boolean found = false; @@ -1958,19 +2029,19 @@ public static boolean replaceAll(List list, T obj, T obj2) { return found; } - /** - * Rotates the elements in {@code list} by the distance {@code dist} - *

- * e.g. for a given list with elements [1, 2, 3, 4, 5, 6, 7, 8, 9, 0], - * calling rotate(list, 3) or rotate(list, -7) would modify the list to look - * like this: [8, 9, 0, 1, 2, 3, 4, 5, 6, 7] - * - * @param lst - * the list whose elements are to be rotated. - * @param dist - * is the distance the list is rotated. This can be any valid - * integer. Negative values rotate the list backwards. - */ + /// Rotates the elements in `list` by the distance `dist` + /// + /// e.g. for a given list with elements [1, 2, 3, 4, 5, 6, 7, 8, 9, 0], + /// calling rotate(list, 3) or rotate(list, -7) would modify the list to look + /// like this: [8, 9, 0, 1, 2, 3, 4, 5, 6, 7] + /// + /// #### Parameters + /// + /// - `lst`: the list whose elements are to be rotated. + /// + /// - `dist`: @param dist + /// is the distance the list is rotated. This can be any valid + /// integer. Negative values rotate the list backwards. @SuppressWarnings("unchecked") public static void rotate(List lst, int dist) { List list = (List) lst; @@ -2016,19 +2087,21 @@ public static void rotate(List lst, int dist) { } } - /** - * Searches the {@code list} for {@code sublist} and returns the beginning - * index of the first occurrence. - *

- * -1 is returned if the {@code sublist} does not exist in {@code list}. - * - * @param list - * the List to search {@code sublist} in. - * @param sublist - * the List to search in {@code list}. - * @return the beginning index of the first occurrence of {@code sublist} in - * {@code list}, or -1. - */ + /// Searches the `list` for `sublist` and returns the beginning + /// index of the first occurrence. + /// + /// -1 is returned if the `sublist` does not exist in `list`. + /// + /// #### Parameters + /// + /// - `list`: the List to search `sublist` in. + /// + /// - `sublist`: the List to search in `list`. + /// + /// #### Returns + /// + /// @return the beginning index of the first occurrence of `sublist` in + /// `list`, or -1. public static int indexOfSubList(List list, List sublist) { int size = list.size(); int sublistSize = sublist.size(); @@ -2083,19 +2156,21 @@ public static int indexOfSubList(List list, List sublist) { return -1; } - /** - * Searches the {@code list} for {@code sublist} and returns the beginning - * index of the last occurrence. - *

- * -1 is returned if the {@code sublist} does not exist in {@code list}. - * - * @param list - * the list to search {@code sublist} in. - * @param sublist - * the list to search in {@code list}. - * @return the beginning index of the last occurrence of {@code sublist} in - * {@code list}, or -1. - */ + /// Searches the `list` for `sublist` and returns the beginning + /// index of the last occurrence. + /// + /// -1 is returned if the `sublist` does not exist in `list`. + /// + /// #### Parameters + /// + /// - `list`: the list to search `sublist` in. + /// + /// - `sublist`: the list to search in `list`. + /// + /// #### Returns + /// + /// @return the beginning index of the last occurrence of `sublist` in + /// `list`, or -1. public static int lastIndexOfSubList(List list, List sublist) { int sublistSize = sublist.size(); int size = list.size(); @@ -2147,27 +2222,30 @@ public static int lastIndexOfSubList(List list, List sublist) { return -1; } - /** - * Returns an {@code ArrayList} with all the elements in the {@code - * enumeration}. The elements in the returned {@code ArrayList} are in the - * same order as in the {@code enumeration}. - * - * @param enumeration - * the source {@link Enumeration}. - * @return an {@code ArrayList} from {@code enumeration}. - */ + /// Returns an `ArrayList` with all the elements in the `enumeration`. The elements in the returned `ArrayList` are in the + /// same order as in the `enumeration`. + /// + /// #### Parameters + /// + /// - `enumeration`: the source `Enumeration`. + /// + /// #### Returns + /// + /// an `ArrayList` from `enumeration`. public static ArrayList list(java.util.Enumeration enumeration) { return null; } - /** - * Returns a wrapper on the specified collection which synchronizes all - * access to the collection. - * - * @param collection - * the Collection to wrap in a synchronized collection. - * @return a synchronized Collection. - */ + /// Returns a wrapper on the specified collection which synchronizes all + /// access to the collection. + /// + /// #### Parameters + /// + /// - `collection`: the Collection to wrap in a synchronized collection. + /// + /// #### Returns + /// + /// a synchronized Collection. public static Collection synchronizedCollection( Collection collection) { if (collection == null) { @@ -2176,14 +2254,16 @@ public static Collection synchronizedCollection( return new SynchronizedCollection(collection); } - /** - * Returns a wrapper on the specified List which synchronizes all access to - * the List. - * - * @param list - * the List to wrap in a synchronized list. - * @return a synchronized List. - */ + /// Returns a wrapper on the specified List which synchronizes all access to + /// the List. + /// + /// #### Parameters + /// + /// - `list`: the List to wrap in a synchronized list. + /// + /// #### Returns + /// + /// a synchronized List. public static List synchronizedList(List list) { if (list == null) { throw new NullPointerException(); @@ -2194,14 +2274,16 @@ public static List synchronizedList(List list) { return new SynchronizedList(list); } - /** - * Returns a wrapper on the specified map which synchronizes all access to - * the map. - * - * @param map - * the map to wrap in a synchronized map. - * @return a synchronized Map. - */ + /// Returns a wrapper on the specified map which synchronizes all access to + /// the map. + /// + /// #### Parameters + /// + /// - `map`: the map to wrap in a synchronized map. + /// + /// #### Returns + /// + /// a synchronized Map. public static Map synchronizedMap(Map map) { if (map == null) { throw new NullPointerException(); @@ -2209,14 +2291,16 @@ public static Map synchronizedMap(Map map) { return new SynchronizedMap(map); } - /** - * Returns a wrapper on the specified set which synchronizes all access to - * the set. - * - * @param set - * the set to wrap in a synchronized set. - * @return a synchronized set. - */ + /// Returns a wrapper on the specified set which synchronizes all access to + /// the set. + /// + /// #### Parameters + /// + /// - `set`: the set to wrap in a synchronized set. + /// + /// #### Returns + /// + /// a synchronized set. public static Set synchronizedSet(Set set) { if (set == null) { throw new NullPointerException(); @@ -2224,14 +2308,16 @@ public static Set synchronizedSet(Set set) { return new SynchronizedSet(set); } - /** - * Returns a wrapper on the specified sorted map which synchronizes all - * access to the sorted map. - * - * @param map - * the sorted map to wrap in a synchronized sorted map. - * @return a synchronized sorted map. - */ + /// Returns a wrapper on the specified sorted map which synchronizes all + /// access to the sorted map. + /// + /// #### Parameters + /// + /// - `map`: the sorted map to wrap in a synchronized sorted map. + /// + /// #### Returns + /// + /// a synchronized sorted map. public static SortedMap synchronizedSortedMap( SortedMap map) { if (map == null) { @@ -2240,14 +2326,16 @@ public static SortedMap synchronizedSortedMap( return new SynchronizedSortedMap(map); } - /** - * Returns a wrapper on the specified sorted set which synchronizes all - * access to the sorted set. - * - * @param set - * the sorted set to wrap in a synchronized sorted set. - * @return a synchronized sorted set. - */ + /// Returns a wrapper on the specified sorted set which synchronizes all + /// access to the sorted set. + /// + /// #### Parameters + /// + /// - `set`: the sorted set to wrap in a synchronized sorted set. + /// + /// #### Returns + /// + /// a synchronized sorted set. public static SortedSet synchronizedSortedSet(SortedSet set) { if (set == null) { throw new NullPointerException(); @@ -2255,15 +2343,17 @@ public static SortedSet synchronizedSortedSet(SortedSet set) { return new SynchronizedSortedSet(set); } - /** - * Returns a wrapper on the specified collection which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the collection. - * - * @param collection - * the collection to wrap in an unmodifiable collection. - * @return an unmodifiable collection. - */ + /// Returns a wrapper on the specified collection which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection to wrap in an unmodifiable collection. + /// + /// #### Returns + /// + /// an unmodifiable collection. @SuppressWarnings("unchecked") public static Collection unmodifiableCollection( Collection collection) { @@ -2273,15 +2363,17 @@ public static Collection unmodifiableCollection( return new UnmodifiableCollection((Collection) collection); } - /** - * Returns a wrapper on the specified list which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the list. - * - * @param list - * the list to wrap in an unmodifiable list. - * @return an unmodifiable List. - */ + /// Returns a wrapper on the specified list which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the list. + /// + /// #### Parameters + /// + /// - `list`: the list to wrap in an unmodifiable list. + /// + /// #### Returns + /// + /// an unmodifiable List. @SuppressWarnings("unchecked") public static List unmodifiableList(List list) { if (list == null) { @@ -2293,15 +2385,17 @@ public static List unmodifiableList(List list) { return new UnmodifiableList((List) list); } - /** - * Returns a wrapper on the specified map which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the map. - * - * @param map - * the map to wrap in an unmodifiable map. - * @return a unmodifiable map. - */ + /// Returns a wrapper on the specified map which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the map. + /// + /// #### Parameters + /// + /// - `map`: the map to wrap in an unmodifiable map. + /// + /// #### Returns + /// + /// a unmodifiable map. @SuppressWarnings("unchecked") public static Map unmodifiableMap( Map map) { @@ -2311,15 +2405,17 @@ public static Map unmodifiableMap( return new UnmodifiableMap((Map) map); } - /** - * Returns a wrapper on the specified set which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the set. - * - * @param set - * the set to wrap in an unmodifiable set. - * @return a unmodifiable set - */ + /// Returns a wrapper on the specified set which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the set. + /// + /// #### Parameters + /// + /// - `set`: the set to wrap in an unmodifiable set. + /// + /// #### Returns + /// + /// a unmodifiable set @SuppressWarnings("unchecked") public static Set unmodifiableSet(Set set) { if (set == null) { @@ -2328,15 +2424,17 @@ public static Set unmodifiableSet(Set set) { return new UnmodifiableSet((Set) set); } - /** - * Returns a wrapper on the specified sorted map which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the sorted map. - * - * @param map - * the sorted map to wrap in an unmodifiable sorted map. - * @return a unmodifiable sorted map - */ + /// Returns a wrapper on the specified sorted map which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the sorted map. + /// + /// #### Parameters + /// + /// - `map`: the sorted map to wrap in an unmodifiable sorted map. + /// + /// #### Returns + /// + /// a unmodifiable sorted map @SuppressWarnings("unchecked") public static SortedMap unmodifiableSortedMap( SortedMap map) { @@ -2346,15 +2444,17 @@ public static SortedMap unmodifiableSortedMap( return new UnmodifiableSortedMap((SortedMap) map); } - /** - * Returns a wrapper on the specified sorted set which throws an - * {@code UnsupportedOperationException} whenever an attempt is made to - * modify the sorted set. - * - * @param set - * the sorted set to wrap in an unmodifiable sorted set. - * @return a unmodifiable sorted set. - */ + /// Returns a wrapper on the specified sorted set which throws an + /// `UnsupportedOperationException` whenever an attempt is made to + /// modify the sorted set. + /// + /// #### Parameters + /// + /// - `set`: the sorted set to wrap in an unmodifiable sorted set. + /// + /// #### Returns + /// + /// a unmodifiable sorted set. public static SortedSet unmodifiableSortedSet(SortedSet set) { if (set == null) { throw new NullPointerException(); @@ -2362,20 +2462,27 @@ public static SortedSet unmodifiableSortedSet(SortedSet set) { return new UnmodifiableSortedSet(set); } - /** - * Returns the number of elements in the {@code Collection} that match the - * {@code Object} passed. If the {@code Object} is {@code null}, then the - * number of {@code null} elements is returned. - * - * @param c - * the {@code Collection} to search. - * @param o - * the {@code Object} to search for. - * @return the number of matching elements. - * @throws NullPointerException - * if the {@code Collection} parameter is {@code null}. - * @since 1.5 - */ + /// Returns the number of elements in the `Collection` that match the + /// `Object` passed. If the `Object` is `null`, then the + /// number of `null` elements is returned. + /// + /// #### Parameters + /// + /// - `c`: the `Collection` to search. + /// + /// - `o`: the `Object` to search for. + /// + /// #### Returns + /// + /// the number of matching elements. + /// + /// #### Throws + /// + /// - `NullPointerException`: if the `Collection` parameter is `null`. + /// + /// #### Since + /// + /// 1.5 public static int frequency(Collection c, Object o) { if (c == null) { throw new NullPointerException(); @@ -2394,78 +2501,104 @@ public static int frequency(Collection c, Object o) { return result; } - /** - * Returns a type-safe empty, immutable {@link List}. - * - * @return an empty {@link List}. - * @since 1.5 - * @see #EMPTY_LIST - */ + /// Returns a type-safe empty, immutable `List`. + /// + /// #### Returns + /// + /// an empty `List`. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #EMPTY_LIST @SuppressWarnings("unchecked") public static final List emptyList() { return EMPTY_LIST; } - /** - * Returns a type-safe empty, immutable {@link Set}. - * - * @return an empty {@link Set}. - * @since 1.5 - * @see #EMPTY_SET - */ + /// Returns a type-safe empty, immutable `Set`. + /// + /// #### Returns + /// + /// an empty `Set`. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #EMPTY_SET @SuppressWarnings("unchecked") public static final Set emptySet() { return EMPTY_SET; } - /** - * Returns a type-safe empty, immutable {@link Map}. - * - * @return an empty {@link Map}. - * @since 1.5 - * @see #EMPTY_MAP - */ + /// Returns a type-safe empty, immutable `Map`. + /// + /// #### Returns + /// + /// an empty `Map`. + /// + /// #### Since + /// + /// 1.5 + /// + /// #### See also + /// + /// - #EMPTY_MAP @SuppressWarnings("unchecked") public static final Map emptyMap() { return EMPTY_MAP; } - /** - * Returns a dynamically typesafe view of the specified collection. Trying - * to insert an element of the wrong type into this collection throws a - * {@code ClassCastException}. At creation time the types in {@code c} are - * not checked for correct type. - * - * @param c - * the collection to be wrapped in a typesafe collection. - * @param type - * the type of the elements permitted to insert. - * @return a typesafe collection. - */ + /// Returns a dynamically typesafe view of the specified collection. Trying + /// to insert an element of the wrong type into this collection throws a + /// `ClassCastException`. At creation time the types in `c` are + /// not checked for correct type. + /// + /// #### Parameters + /// + /// - `c`: the collection to be wrapped in a typesafe collection. + /// + /// - `type`: the type of the elements permitted to insert. + /// + /// #### Returns + /// + /// a typesafe collection. public static Collection checkedCollection(Collection c, Class type) { return new CheckedCollection(c, type); } - /** - * Adds all the specified elements to the specified collection. - * - * @param c - * the collection the elements are to be inserted into. - * @param a - * the elements to insert. - * @return true if the collection changed during insertion. - * @throws UnsupportedOperationException - * when the method is not supported. - * @throws NullPointerException - * when {@code c} or {@code a} is {@code null}, or {@code a} - * contains one or more {@code null} elements and {@code c} - * doesn't support {@code null} elements. - * @throws IllegalArgumentException - * if at least one of the elements can't be inserted into the - * collection. - */ + /// Adds all the specified elements to the specified collection. + /// + /// #### Parameters + /// + /// - `c`: the collection the elements are to be inserted into. + /// + /// - `a`: the elements to insert. + /// + /// #### Returns + /// + /// true if the collection changed during insertion. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when the method is not supported. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when `c` or `a` is `null`, or `a` + /// contains one or more `null` elements and `c` + /// doesn't support `null` elements. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if at least one of the elements can't be inserted into the + /// collection. public static boolean addAll(Collection c, T... a) { boolean modified = false; for (int i = 0; i < a.length; i++) { @@ -2474,18 +2607,22 @@ public static boolean addAll(Collection c, T... a) { return modified; } - /** - * Returns whether the specified collections have no elements in common. - * - * @param c1 - * the first collection. - * @param c2 - * the second collection. - * @return {@code true} if the collections have no elements in common, - * {@code false} otherwise. - * @throws NullPointerException - * if one of the collections is {@code null}. - */ + /// Returns whether the specified collections have no elements in common. + /// + /// #### Parameters + /// + /// - `c1`: the first collection. + /// + /// - `c2`: the second collection. + /// + /// #### Returns + /// + /// @return `true` if the collections have no elements in common, + /// `false` otherwise. + /// + /// #### Throws + /// + /// - `NullPointerException`: if one of the collections is `null`. public static boolean disjoint(Collection c1, Collection c2) { if ((c1 instanceof Set) && !(c2 instanceof Set) || (c2.size()) > c1.size()) { @@ -2502,16 +2639,20 @@ public static boolean disjoint(Collection c1, Collection c2) { return true; } - /** - * Checks if specified object is instance of specified class. Used for a - * dynamically typesafe view of the collections. - * - * @param obj - - * object is to be checked - * @param type - - * class of object that should be - * @return specified object - */ + /// Checks if specified object is instance of specified class. Used for a + /// dynamically typesafe view of the collections. + /// + /// #### Parameters + /// + /// - `obj`: @param obj - + /// object is to be checked + /// + /// - `type`: @param type - + /// class of object that should be + /// + /// #### Returns + /// + /// specified object static E checkType(E obj, Class type) { if (obj != null && !type.isInstance(obj)) { // luni.05=Attempt to insert {0} element into collection with @@ -2521,19 +2662,27 @@ static E checkType(E obj, Class type) { return obj; } - /** - * Answers a set backed by a map. And the map must be empty when this method - * is called. - * - * @param - * type of elements in set - * @param map - * the backing map - * @return the set from the map - * @throws IllegalArgumentException - * if the map is not empty - * @since 1.6 - */ + /// Answers a set backed by a map. And the map must be empty when this method + /// is called. + /// + /// @param + /// type of elements in set + /// + /// #### Parameters + /// + /// - `map`: the backing map + /// + /// #### Returns + /// + /// the set from the map + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if the map is not empty + /// + /// #### Since + /// + /// 1.6 public static Set newSetFromMap(Map map) { if (map.isEmpty()) { return new SetFromMap(map); @@ -2541,17 +2690,23 @@ public static Set newSetFromMap(Map map) { throw new IllegalArgumentException(); } - /** - * Answers a LIFO Queue as a view of a Deque. Methods in the returned Queue - * need to be re-written to implement the LIFO feature. - * - * @param - * type of elements - * @param deque - * the Deque - * @return the LIFO Queue - * @since 1.6 - */ + /// Answers a LIFO Queue as a view of a Deque. Methods in the returned Queue + /// need to be re-written to implement the LIFO feature. + /// + /// @param + /// type of elements + /// + /// #### Parameters + /// + /// - `deque`: the Deque + /// + /// #### Returns + /// + /// the LIFO Queue + /// + /// #### Since + /// + /// 1.6 public static Queue asLifoQueue(Deque deque) { return new AsLIFOQueue(deque); } @@ -2739,9 +2894,7 @@ public String toString() { } } - /** - * Class represents a dynamically typesafe view of the specified collection. - */ + /// Class represents a dynamically typesafe view of the specified collection. private static class CheckedCollection implements Collection { private static final long serialVersionUID = 1578914078182001775L; @@ -2750,13 +2903,13 @@ private static class CheckedCollection implements Collection { Class type; - /** - * Constructs a dynamically typesafe view of the specified collection. - * - * @param c - - * the collection for which an unmodifiable view is to be - * constructed. - */ + /// Constructs a dynamically typesafe view of the specified collection. + /// + /// #### Parameters + /// + /// - `c`: @param c - + /// the collection for which an unmodifiable view is to be + /// constructed. public CheckedCollection(Collection c, Class type) { if (c == null || type == null) { throw new NullPointerException(); @@ -2765,30 +2918,30 @@ public CheckedCollection(Collection c, Class type) { this.type = type; } - /** - * @see java.util.Collection#size() - */ + /// #### See also + /// + /// - java.util.Collection#size() public int size() { return c.size(); } - /** - * @see java.util.Collection#isEmpty() - */ + /// #### See also + /// + /// - java.util.Collection#isEmpty() public boolean isEmpty() { return c.isEmpty(); } - /** - * @see java.util.Collection#contains(Object) - */ + /// #### See also + /// + /// - java.util.Collection#contains(Object) public boolean contains(Object obj) { return c.contains(obj); } - /** - * @see java.util.Collection#iterator() - */ + /// #### See also + /// + /// - java.util.Collection#iterator() public Iterator iterator() { Iterator i = c.iterator(); if (i instanceof ListIterator) { @@ -2797,44 +2950,44 @@ public Iterator iterator() { return i; } - /** - * @see java.util.Collection#toArray() - */ + /// #### See also + /// + /// - java.util.Collection#toArray() public Object[] toArray() { return c.toArray(); } - /** - * @see java.util.Collection#toArray(Object[]) - */ + /// #### See also + /// + /// - java.util.Collection#toArray(Object[]) public T[] toArray(T[] arr) { return c.toArray(arr); } - /** - * @see java.util.Collection#add(Object) - */ + /// #### See also + /// + /// - java.util.Collection#add(Object) public boolean add(E obj) { return c.add(checkType(obj, type)); } - /** - * @see java.util.Collection#remove(Object) - */ + /// #### See also + /// + /// - java.util.Collection#remove(Object) public boolean remove(Object obj) { return c.remove(obj); } - /** - * @see java.util.Collection#containsAll(Collection) - */ + /// #### See also + /// + /// - java.util.Collection#containsAll(Collection) public boolean containsAll(Collection c1) { return c.containsAll(c1); } - /** - * @see java.util.Collection#addAll(Collection) - */ + /// #### See also + /// + /// - java.util.Collection#addAll(Collection) @SuppressWarnings("unchecked") public boolean addAll(Collection c1) { Object[] array = c1.toArray(); @@ -2844,117 +2997,115 @@ public boolean addAll(Collection c1) { return c.addAll((List) Arrays.asList(array)); } - /** - * @see java.util.Collection#removeAll(Collection) - */ + /// #### See also + /// + /// - java.util.Collection#removeAll(Collection) public boolean removeAll(Collection c1) { return c.removeAll(c1); } - /** - * @see java.util.Collection#retainAll(Collection) - */ + /// #### See also + /// + /// - java.util.Collection#retainAll(Collection) public boolean retainAll(Collection c1) { return c.retainAll(c1); } - /** - * @see java.util.Collection#clear() - */ + /// #### See also + /// + /// - java.util.Collection#clear() public void clear() { c.clear(); } - /** - * @see java.lang.Object#toString() - */ + /// #### See also + /// + /// - java.lang.Object#toString() @Override public String toString() { return c.toString(); } } - /** - * Class represents a dynamically typesafe view of the specified - * ListIterator. - */ + /// Class represents a dynamically typesafe view of the specified + /// ListIterator. private static class CheckedListIterator implements ListIterator { private ListIterator i; private Class type; - /** - * Constructs a dynamically typesafe view of the specified ListIterator. - * - * @param i - - * the listIterator for which a dynamically typesafe view to - * be constructed. - */ + /// Constructs a dynamically typesafe view of the specified ListIterator. + /// + /// #### Parameters + /// + /// - `i`: @param i - + /// the listIterator for which a dynamically typesafe view to + /// be constructed. public CheckedListIterator(ListIterator i, Class type) { this.i = i; this.type = type; } - /** - * @see java.util.Iterator#hasNext() - */ + /// #### See also + /// + /// - java.util.Iterator#hasNext() public boolean hasNext() { return i.hasNext(); } - /** - * @see java.util.Iterator#next() - */ + /// #### See also + /// + /// - java.util.Iterator#next() public E next() { return i.next(); } - /** - * @see java.util.Iterator#remove() - */ + /// #### See also + /// + /// - java.util.Iterator#remove() public void remove() { i.remove(); } - /** - * @see java.util.ListIterator#hasPrevious() - */ + /// #### See also + /// + /// - java.util.ListIterator#hasPrevious() public boolean hasPrevious() { return i.hasPrevious(); } - /** - * @see java.util.ListIterator#previous() - */ + /// #### See also + /// + /// - java.util.ListIterator#previous() public E previous() { return i.previous(); } - /** - * @see java.util.ListIterator#nextIndex() - */ + /// #### See also + /// + /// - java.util.ListIterator#nextIndex() public int nextIndex() { return i.nextIndex(); } - /** - * @see java.util.ListIterator#previousIndex() - */ + /// #### See also + /// + /// - java.util.ListIterator#previousIndex() public int previousIndex() { return i.previousIndex(); } - /** - * @see java.util.ListIterator#set(Object) - */ + /// #### See also + /// + /// - java.util.ListIterator#set(Object) public void set(E obj) { i.set(checkType(obj, type)); } - /** - * @see java.util.ListIterator#add(Object) - */ + /// #### See also + /// + /// - java.util.ListIterator#add(Object) public void add(E obj) { i.add(checkType(obj, type)); } diff --git a/Ports/CLDC11/src/java/util/Comparator.java b/Ports/CLDC11/src/java/util/Comparator.java index 9a05ee909c..8a571fba41 100644 --- a/Ports/CLDC11/src/java/util/Comparator.java +++ b/Ports/CLDC11/src/java/util/Comparator.java @@ -17,57 +17,65 @@ package java.util; -/** - * A {@code Comparator} is used to compare two objects to determine their ordering with - * respect to each other. On a given {@code Collection}, a {@code Comparator} can be used to - * obtain a sorted {@code Collection} which is totally ordered. For a {@code Comparator} - * to be consistent with equals, its {code #compare(Object, Object)} - * method has to return zero for each pair of elements (a,b) where a.equals(b) - * holds true. It is recommended that a {@code Comparator} implements - * {@link java.io.Serializable}. - * - * @since 1.2 - */ +/// A `Comparator` is used to compare two objects to determine their ordering with +/// respect to each other. On a given `Collection`, a `Comparator` can be used to +/// obtain a sorted `Collection` which is *totally ordered*. For a `Comparator` +/// to be *consistent with equals*, its {code #compare(Object, Object)} +/// method has to return zero for each pair of elements (a,b) where a.equals(b) +/// holds true. It is recommended that a `Comparator` implements +/// `java.io.Serializable`. +/// +/// #### Since +/// +/// 1.2 public interface Comparator { - /** - * Compares the two specified objects to determine their relative ordering. The ordering - * implied by the return value of this method for all possible pairs of - * {@code (object1, object2)} should form an equivalence relation. - * This means that - *

    - *
  • {@code compare(a,a)} returns zero for all {@code a}
    • - *
  • the sign of {@code compare(a,b)} must be the opposite of the sign of {@code - * compare(b,a)} for all pairs of (a,b)
    • - *
  • From {@code compare(a,b) > 0} and {@code compare(b,c) > 0} it must - * follow {@code compare(a,c) > 0} for all possible combinations of {@code - * (a,b,c)}
    • - *
- * - * @param object1 - * an {@code Object}. - * @param object2 - * a second {@code Object} to compare with {@code object1}. - * @return an integer < 0 if {@code object1} is less than {@code object2}, 0 if they are - * equal, and > 0 if {@code object1} is greater than {@code object2}. - * @throws ClassCastException - * if objects are not of the correct type. - */ + /// Compares the two specified objects to determine their relative ordering. The ordering + /// implied by the return value of this method for all possible pairs of + /// `(object1, object2)` should form an *equivalence relation*. + /// This means that + /// + /// - `compare(a,a)` returns zero for all `a` + /// + /// - the sign of `compare(a,b)` must be the opposite of the sign of `compare(b,a)` for all pairs of (a,b) + /// + /// - From `compare(a,b) > 0` and `compare(b,c) > 0` it must + /// follow `compare(a,c) > 0` for all possible combinations of `(a,b,c)` + /// + /// #### Parameters + /// + /// - `object1`: an `Object`. + /// + /// - `object2`: a second `Object` to compare with `object1`. + /// + /// #### Returns + /// + /// an integer 0 if `object1` is greater than `object2`. + /// + /// #### Throws + /// + /// - `ClassCastException`: if objects are not of the correct type. public int compare(T object1, T object2); - /** - * Compares this {@code Comparator} with the specified {@code Object} and indicates whether they - * are equal. In order to be equal, {@code object} must represent the same object - * as this instance using a class-specific comparison. - *

- * A {@code Comparator} never needs to override this method, but may choose so for - * performance reasons. - * - * @param object - * the {@code Object} to compare with this comparator. - * @return boolean {@code true} if specified {@code Object} is the same as this - * {@code Object}, and {@code false} otherwise. - * @see Object#hashCode - * @see Object#equals - */ + /// Compares this `Comparator` with the specified `Object` and indicates whether they + /// are equal. In order to be equal, `object` must represent the same object + /// as this instance using a class-specific comparison. + /// + /// A `Comparator` never needs to override this method, but may choose so for + /// performance reasons. + /// + /// #### Parameters + /// + /// - `object`: the `Object` to compare with this comparator. + /// + /// #### Returns + /// + /// @return boolean `true` if specified `Object` is the same as this + /// `Object`, and `false` otherwise. + /// + /// #### See also + /// + /// - Object#hashCode + /// + /// - Object#equals public boolean equals(Object object); } diff --git a/Ports/CLDC11/src/java/util/ConcurrentModificationException.java b/Ports/CLDC11/src/java/util/ConcurrentModificationException.java index a9ca4e3de6..78a54928a5 100644 --- a/Ports/CLDC11/src/java/util/ConcurrentModificationException.java +++ b/Ports/CLDC11/src/java/util/ConcurrentModificationException.java @@ -17,32 +17,29 @@ package java.util; -/** - * An {@code ConcurrentModificationException} is thrown when a Collection is - * modified and an existing iterator on the Collection is used to modify the - * Collection as well. - * - * @see java.lang.RuntimeException - */ +/// An `ConcurrentModificationException` is thrown when a Collection is +/// modified and an existing iterator on the Collection is used to modify the +/// Collection as well. +/// +/// #### See also +/// +/// - java.lang.RuntimeException public class ConcurrentModificationException extends RuntimeException { private static final long serialVersionUID = -3666751008965953603L; - /** - * Constructs a new {@code ConcurrentModificationException} with the current - * stack trace filled in. - */ + /// Constructs a new `ConcurrentModificationException` with the current + /// stack trace filled in. public ConcurrentModificationException() { /*empty*/ } - /** - * Constructs a new {@code ConcurrentModificationException} with the current - * stack trace and message filled in. - * - * @param detailMessage - * the detail message for the exception. - */ + /// Constructs a new `ConcurrentModificationException` with the current + /// stack trace and message filled in. + /// + /// #### Parameters + /// + /// - `detailMessage`: the detail message for the exception. public ConcurrentModificationException(String detailMessage) { super(detailMessage); } diff --git a/Ports/CLDC11/src/java/util/Date.java b/Ports/CLDC11/src/java/util/Date.java index 5ff87dbcb1..9c70c03995 100644 --- a/Ports/CLDC11/src/java/util/Date.java +++ b/Ports/CLDC11/src/java/util/Date.java @@ -22,62 +22,46 @@ * have any questions. */ package java.util; -/** - * The class Date represents a specific instant in time, with millisecond precision. - * This class has been subset for the J2ME based on the JDK 1.3 Date class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class. - * Although the Date class is intended to reflect coordinated universal time (UTC), it may not do so exactly, depending on the host environment of the Java Virtual Machine. Nearly all modern operating systems assume that 1 day = 24x60x60 = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second." The leap second is always added as the last second of the day, and always on December 31 or June 30. For example, the last minute of the year 1995 was 61 seconds long, thanks to an added leap second. Most computer clocks are not accurate enough to be able to reflect the leap-second distinction. - * Version: CLDC 1.1 03/13/2002 (Based on JDK 1.3) See Also:TimeZone, Calendar - */ +/// The class Date represents a specific instant in time, with millisecond precision. +/// This class has been subset for the J2ME based on the JDK 1.3 Date class. Many methods and variables have been pruned, and other methods simplified, in an effort to reduce the size of this class. +/// Although the Date class is intended to reflect coordinated universal time (UTC), it may not do so exactly, depending on the host environment of the Java Virtual Machine. Nearly all modern operating systems assume that 1 day = 24x60x60 = 86400 seconds in all cases. In UTC, however, about once every year or two there is an extra second, called a "leap second." The leap second is always added as the last second of the day, and always on December 31 or June 30. For example, the last minute of the year 1995 was 61 seconds long, thanks to an added leap second. Most computer clocks are not accurate enough to be able to reflect the leap-second distinction. +/// Version: CLDC 1.1 03/13/2002 (Based on JDK 1.3) See Also:TimeZone, Calendar public class Date implements Comparable { - /** - * Allocates a Date object and initializes it to represent the current time specified number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. - * See Also:System.currentTimeMillis() - */ + /// Allocates a Date object and initializes it to represent the current time specified number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. + /// See Also:System.currentTimeMillis() public Date(){ //TODO codavaj!! } - /** - * Allocates a Date object and initializes it to represent the specified number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. - * Parameters:date - the milliseconds since January 1, 1970, 00:00:00 GMT.See Also:System.currentTimeMillis() - */ + /// Allocates a Date object and initializes it to represent the specified number of milliseconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT. + /// Parameters:date - the milliseconds since January 1, 1970, 00:00:00 GMT.See Also:System.currentTimeMillis() public Date(long date){ //TODO codavaj!! } - /** - * Compares two dates for equality. The result is true if and only if the argument is not null and is a Date object that represents the same point in time, to the millisecond, as this object. - * Thus, two Date objects are equal if and only if the getTime method returns the same long value for both. - */ + /// Compares two dates for equality. The result is true if and only if the argument is not null and is a Date object that represents the same point in time, to the millisecond, as this object. + /// Thus, two Date objects are equal if and only if the getTime method returns the same long value for both. public boolean equals(java.lang.Object obj){ return false; //TODO codavaj!! } - /** - * Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this Date object. - */ + /// Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this Date object. public long getTime(){ return 0l; //TODO codavaj!! } - /** - * Returns a hash code value for this object. The result is the exclusive OR of the two halves of the primitive long value returned by the - * method. That is, the hash code is the value of the expression: (int)(this.getTime()^(this.getTime() >>> 32)) - */ + /// Returns a hash code value for this object. The result is the exclusive OR of the two halves of the primitive long value returned by the + /// method. That is, the hash code is the value of the expression: (int)(this.getTime()^(this.getTime() >>> 32)) public int hashCode(){ return 0; //TODO codavaj!! } - /** - * Sets this Date object to represent a point in time that is time milliseconds after January 1, 1970 00:00:00 GMT. - */ + /// Sets this Date object to represent a point in time that is time milliseconds after January 1, 1970 00:00:00 GMT. public void setTime(long time){ return; //TODO codavaj!! } - /** - * Converts this Date object to a String of the form: dow mon dd hh:mm:ss zzz yyyy where: dow is the day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat). mon is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec). dd is the day of the month (01 through 31), as two decimal digits. hh is the hour of the day (00 through 23), as two decimal digits. mm is the minute within the hour (00 through 59), as two decimal digits. ss is the second within the minute (00 through 61, as two decimal digits. zzz is the time zone (and may reflect daylight savings time). If time zone information is not available, then zzz is empty - that is, it consists of no characters at all. yyyy is the year, as four decimal digits. - */ + /// Converts this Date object to a String of the form: dow mon dd hh:mm:ss zzz yyyy where: dow is the day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat). mon is the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec). dd is the day of the month (01 through 31), as two decimal digits. hh is the hour of the day (00 through 23), as two decimal digits. mm is the minute within the hour (00 through 59), as two decimal digits. ss is the second within the minute (00 through 61, as two decimal digits. zzz is the time zone (and may reflect daylight savings time). If time zone information is not available, then zzz is empty - that is, it consists of no characters at all. yyyy is the year, as four decimal digits. public java.lang.String toString(){ return null; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/util/Deque.java b/Ports/CLDC11/src/java/util/Deque.java index 83091eaf6a..bd004903f4 100644 --- a/Ports/CLDC11/src/java/util/Deque.java +++ b/Ports/CLDC11/src/java/util/Deque.java @@ -17,239 +17,276 @@ package java.util; -/** - * A kind of collection that can insert or remove element at both ends("double - * ended queue"). Mostly a deque has no limit of its size. - * - * Extending from Queue, a deque can be used as a Queue which behavior is - * first-in-first-out. Furthermore, a deque can also be used as a Stack(legacy - * class) which behavior is last-in-first-out. - * - * A typical deque does not allow null to be inserted as its element, while some - * implementations allow it. But null should not be inserted even in these - * implementations, since method poll return null to indicate that there is no - * element left in the deque. - * - * A deque can also remove interior elements by removeFirstOccurrence and - * removeLastOccurrence methods. A deque can not access elements by index. - * - * @param - * the type of elements in this collection - * @since 1.6 - */ +/// A kind of collection that can insert or remove element at both ends("double +/// ended queue"). Mostly a deque has no limit of its size. +/// +/// Extending from Queue, a deque can be used as a Queue which behavior is +/// first-in-first-out. Furthermore, a deque can also be used as a Stack(legacy +/// class) which behavior is last-in-first-out. +/// +/// A typical deque does not allow null to be inserted as its element, while some +/// implementations allow it. But null should not be inserted even in these +/// implementations, since method poll return null to indicate that there is no +/// element left in the deque. +/// +/// A deque can also remove interior elements by removeFirstOccurrence and +/// removeLastOccurrence methods. A deque can not access elements by index. +/// +/// @param +/// the type of elements in this collection +/// +/// #### Since +/// +/// 1.6 public interface Deque extends Queue { - /** - * Inserts an element at the head of this deque if it dose not violate size - * limit immediately. It is better to use offerFirst(E) if a deque is - * size-limited. - * - * @param e - * the element - * @throws IllegalStateException - * if it can not add now due to size limit - * @throws ClassCastException - * if the class of element can not be added into this deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - * @throws IllegalArgumentException - * if the element can not be added due to some property. - */ + /// Inserts an element at the head of this deque if it dose not violate size + /// limit immediately. It is better to use offerFirst(E) if a deque is + /// size-limited. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Throws + /// + /// - `IllegalStateException`: if it can not add now due to size limit + /// + /// - `ClassCastException`: if the class of element can not be added into this deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element + /// + /// - `IllegalArgumentException`: if the element can not be added due to some property. void addFirst(E e); - /** - * Inserts an element at the tail of this deque if it dose not violate size - * limit immediately. It is better to use offerLast(E) if a deque is - * size-limited. - * - * @param e - * the element - * @throws IllegalStateException - * if it can not add now due to size limit - * @throws ClassCastException - * if the class of element can not be added into this deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - * @throws IllegalArgumentException - * if the element can not be added due to some property. - */ + /// Inserts an element at the tail of this deque if it dose not violate size + /// limit immediately. It is better to use offerLast(E) if a deque is + /// size-limited. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Throws + /// + /// - `IllegalStateException`: if it can not add now due to size limit + /// + /// - `ClassCastException`: if the class of element can not be added into this deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element + /// + /// - `IllegalArgumentException`: if the element can not be added due to some property. void addLast(E e); - /** - * Inserts an element at the head of this deque unless it would violate size - * limit. It is better than the addFirst(E) method in a size-limited deque, - * because the latter one may fail to add the element only by throwing an - * exception. - * - * @param e - * the element - * @return true if the operation succeeds or false if it fails. - * @throws ClassCastException - * if the class of element can not be added into this deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - * @throws IllegalArgumentException - * if the element can not be added due to some property. - */ + /// Inserts an element at the head of this deque unless it would violate size + /// limit. It is better than the addFirst(E) method in a size-limited deque, + /// because the latter one may fail to add the element only by throwing an + /// exception. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true if the operation succeeds or false if it fails. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of element can not be added into this deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element + /// + /// - `IllegalArgumentException`: if the element can not be added due to some property. boolean offerFirst(E e); - /** - * Inserts an element at the tail of this deque unless it would violate size - * limit. It is better than the addLast(E) method in a size-limited deque, - * because the latter one may fail to add the element only by throwing an - * exception. - * - * @param e - * the element - * @return true if the operation succeeds or false if it fails - * @throws ClassCastException - * if the class of element can not be added into this deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - * @throws IllegalArgumentException - * if the element can not be added due to some property - */ + /// Inserts an element at the tail of this deque unless it would violate size + /// limit. It is better than the addLast(E) method in a size-limited deque, + /// because the latter one may fail to add the element only by throwing an + /// exception. + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Returns + /// + /// true if the operation succeeds or false if it fails + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of element can not be added into this deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element + /// + /// - `IllegalArgumentException`: if the element can not be added due to some property boolean offerLast(E e); - /** - * Gets and removes the head element of this deque. This method throws an - * exception if the deque is empty. - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - */ + /// Gets and removes the head element of this deque. This method throws an + /// exception if the deque is empty. + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty E removeFirst(); - /** - * Gets and removes the tail element of this deque. This method throws an - * exception if the deque is empty. - * - * @return the tail element - * @throws NoSuchElementException - * if the deque is empty - */ + /// Gets and removes the tail element of this deque. This method throws an + /// exception if the deque is empty. + /// + /// #### Returns + /// + /// the tail element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty E removeLast(); - /** - * Gets and removes the head element of this deque. This method returns null - * if the deque is empty. - * - * @return the head element or null if the deque is empty - */ + /// Gets and removes the head element of this deque. This method returns null + /// if the deque is empty. + /// + /// #### Returns + /// + /// the head element or null if the deque is empty E pollFirst(); - /** - * Gets and removes the tail element of this deque. This method returns null - * if the deque is empty. - * - * @return the tail element or null if the deque is empty - */ + /// Gets and removes the tail element of this deque. This method returns null + /// if the deque is empty. + /// + /// #### Returns + /// + /// the tail element or null if the deque is empty E pollLast(); - /** - * Gets but not removes the head element of this deque. This method throws - * an exception if the deque is empty. - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - */ + /// Gets but not removes the head element of this deque. This method throws + /// an exception if the deque is empty. + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty E getFirst(); - /** - * Gets but not removes the tail element of this deque. This method throws - * an exception if the deque is empty. - * - * @return the tail element - * @throws NoSuchElementException - * if the deque is empty - */ + /// Gets but not removes the tail element of this deque. This method throws + /// an exception if the deque is empty. + /// + /// #### Returns + /// + /// the tail element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty E getLast(); - /** - * Gets but not removes the head element of this deque. This method returns - * null if the deque is empty. - * - * @return the head element or null if the deque is empty - */ + /// Gets but not removes the head element of this deque. This method returns + /// null if the deque is empty. + /// + /// #### Returns + /// + /// the head element or null if the deque is empty E peekFirst(); - /** - * Gets but not removes the tail element of this deque. This method returns - * null if the deque is empty. - * - * @return the tail element or null if the deque is empty - */ + /// Gets but not removes the tail element of this deque. This method returns + /// null if the deque is empty. + /// + /// #### Returns + /// + /// the tail element or null if the deque is empty E peekLast(); - /** - * Removes the first equivalent element of the specified object. If the - * deque does not contain the element, it is unchanged and returns false. - * - * @param o - * the element to be removed - * @return true if the operation succeeds or false if the deque does not - * contain the element. - * @throws ClassCastException - * if the class of the element is incompatible with the deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - */ + /// Removes the first equivalent element of the specified object. If the + /// deque does not contain the element, it is unchanged and returns false. + /// + /// #### Parameters + /// + /// - `o`: the element to be removed + /// + /// #### Returns + /// + /// @return true if the operation succeeds or false if the deque does not + /// contain the element. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of the element is incompatible with the deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element boolean removeFirstOccurrence(Object o); - /** - * Removes the last equivalent element of the specified object. If the deque - * does not contain the element, it is unchanged and returns false. - * - * @param o - * the element to be removed - * @return true if the operation succeeds or false if the deque does not - * contain the element. - * @throws ClassCastException - * if the class of the element is incompatible with the deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - */ + /// Removes the last equivalent element of the specified object. If the deque + /// does not contain the element, it is unchanged and returns false. + /// + /// #### Parameters + /// + /// - `o`: the element to be removed + /// + /// #### Returns + /// + /// @return true if the operation succeeds or false if the deque does not + /// contain the element. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of the element is incompatible with the deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element boolean removeLastOccurrence(Object o); - /** - * Pushes the element to the deque(at the head of the deque), just same as - * addFirst(E). - * - * @param e - * the element - * @throws IllegalStateException - * if it can not add now due to size limit - * @throws ClassCastException - * if the class of element can not be added into this deque - * @throws NullPointerException - * if the element is null and the deque can not contain null - * element - * @throws IllegalArgumentException - * if the element can not be added due to some property. - */ + /// Pushes the element to the deque(at the head of the deque), just same as + /// addFirst(E). + /// + /// #### Parameters + /// + /// - `e`: the element + /// + /// #### Throws + /// + /// - `IllegalStateException`: if it can not add now due to size limit + /// + /// - `ClassCastException`: if the class of element can not be added into this deque + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the element is null and the deque can not contain null + /// element + /// + /// - `IllegalArgumentException`: if the element can not be added due to some property. void push(E e); - /** - * Pops the head element of the deque, just same as removeFirst(). - * - * @return the head element - * @throws NoSuchElementException - * if the deque is empty - */ + /// Pops the head element of the deque, just same as removeFirst(). + /// + /// #### Returns + /// + /// the head element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if the deque is empty E pop(); - /** - * Returns the iterator in reverse order, from tail to head. - * - * @return the iterator in reverse order - */ + /// Returns the iterator in reverse order, from tail to head. + /// + /// #### Returns + /// + /// the iterator in reverse order Iterator descendingIterator(); } diff --git a/Ports/CLDC11/src/java/util/Dictionary.java b/Ports/CLDC11/src/java/util/Dictionary.java index 88191b007c..f67f90222c 100644 --- a/Ports/CLDC11/src/java/util/Dictionary.java +++ b/Ports/CLDC11/src/java/util/Dictionary.java @@ -17,100 +17,134 @@ package java.util; -/** - * Note: Do not use this class since it is obsolete. Please use the - * {@link Map} interface for new implementations. - *

- * Dictionary is an abstract class which is the superclass of all classes that - * associate keys with values, such as {@code Hashtable}. - * - * @see Hashtable - * @since 1.0 - */ +/// **Note: Do not use this class since it is obsolete. Please use the +/// `Map` interface for new implementations.** +/// +/// Dictionary is an abstract class which is the superclass of all classes that +/// associate keys with values, such as `Hashtable`. +/// +/// #### Since +/// +/// 1.0 +/// +/// #### See also +/// +/// - Hashtable public abstract class Dictionary { - /** - * Constructs a new instance of this class. - */ + /// Constructs a new instance of this class. public Dictionary() { super(); } - /** - * Returns an enumeration on the elements of this dictionary. - * - * @return an enumeration of the values of this dictionary. - * @see #keys - * @see #size - * @see Enumeration - */ + /// Returns an enumeration on the elements of this dictionary. + /// + /// #### Returns + /// + /// an enumeration of the values of this dictionary. + /// + /// #### See also + /// + /// - #keys + /// + /// - #size + /// + /// - Enumeration public abstract java.util.Enumeration elements(); - /** - * Returns the value which is associated with {@code key}. - * - * @param key - * the key of the value returned. - * @return the value associated with {@code key}, or {@code null} if the - * specified key does not exist. - * @see #put - */ + /// Returns the value which is associated with `key`. + /// + /// #### Parameters + /// + /// - `key`: the key of the value returned. + /// + /// #### Returns + /// + /// @return the value associated with `key`, or `null` if the + /// specified key does not exist. + /// + /// #### See also + /// + /// - #put public abstract V get(Object key); - /** - * Returns true if this dictionary has no key/value pairs. - * - * @return {@code true} if this dictionary has no key/value pairs, - * {@code false} otherwise. - * @see #size - */ + /// Returns true if this dictionary has no key/value pairs. + /// + /// #### Returns + /// + /// @return `true` if this dictionary has no key/value pairs, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #size public abstract boolean isEmpty(); - /** - * Returns an enumeration on the keys of this dictionary. - * - * @return an enumeration of the keys of this dictionary. - * @see #elements - * @see #size - * @see Enumeration - */ + /// Returns an enumeration on the keys of this dictionary. + /// + /// #### Returns + /// + /// an enumeration of the keys of this dictionary. + /// + /// #### See also + /// + /// - #elements + /// + /// - #size + /// + /// - Enumeration public abstract java.util.Enumeration keys(); - /** - * Associate {@code key} with {@code value} in this dictionary. If {@code - * key} exists in the dictionary before this call, the old value in the - * dictionary is replaced by {@code value}. - * - * @param key - * the key to add. - * @param value - * the value to add. - * @return the old value previously associated with {@code key} or {@code - * null} if {@code key} is new to the dictionary. - * @see #elements - * @see #get - * @see #keys - */ + /// Associate `key` with `value` in this dictionary. If `key` exists in the dictionary before this call, the old value in the + /// dictionary is replaced by `value`. + /// + /// #### Parameters + /// + /// - `key`: the key to add. + /// + /// - `value`: the value to add. + /// + /// #### Returns + /// + /// the old value previously associated with `key` or `null` if `key` is new to the dictionary. + /// + /// #### See also + /// + /// - #elements + /// + /// - #get + /// + /// - #keys public abstract V put(K key, V value); - /** - * Removes the key/value pair with the specified {@code key} from this - * dictionary. - * - * @param key - * the key to remove. - * @return the associated value before the deletion or {@code null} if - * {@code key} was not known to this dictionary. - * @see #get - * @see #put - */ + /// Removes the key/value pair with the specified `key` from this + /// dictionary. + /// + /// #### Parameters + /// + /// - `key`: the key to remove. + /// + /// #### Returns + /// + /// @return the associated value before the deletion or `null` if + /// `key` was not known to this dictionary. + /// + /// #### See also + /// + /// - #get + /// + /// - #put public abstract V remove(Object key); - /** - * Returns the number of key/value pairs in this dictionary. - * - * @return the number of key/value pairs in this dictionary. - * @see #elements - * @see #keys - */ + /// Returns the number of key/value pairs in this dictionary. + /// + /// #### Returns + /// + /// the number of key/value pairs in this dictionary. + /// + /// #### See also + /// + /// - #elements + /// + /// - #keys public abstract int size(); } diff --git a/Ports/CLDC11/src/java/util/EmptyStackException.java b/Ports/CLDC11/src/java/util/EmptyStackException.java index e256fdea63..5098ffa4b5 100644 --- a/Ports/CLDC11/src/java/util/EmptyStackException.java +++ b/Ports/CLDC11/src/java/util/EmptyStackException.java @@ -22,14 +22,10 @@ * have any questions. */ package java.util; -/** - * Thrown by methods in the Stack class to indicate that the stack is empty. - * Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:Stack - */ +/// Thrown by methods in the Stack class to indicate that the stack is empty. +/// Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:Stack public class EmptyStackException extends java.lang.RuntimeException{ - /** - * Constructs a new EmptyStackException with null as its error message string. - */ + /// Constructs a new EmptyStackException with null as its error message string. public EmptyStackException(){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/util/Enumeration.java b/Ports/CLDC11/src/java/util/Enumeration.java index 6e6c21fdea..888da3753a 100644 --- a/Ports/CLDC11/src/java/util/Enumeration.java +++ b/Ports/CLDC11/src/java/util/Enumeration.java @@ -22,21 +22,15 @@ * have any questions. */ package java.util; -/** - * An object that implements the Enumeration interface generates a series of elements, one at a time. Successive calls to the nextElement method return successive elements of the series. - * For example, to print all elements of a vector v: - * Methods are provided to enumerate through the elements of a vector, the keys of a hashtable, and the values in a hashtable. - * Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:nextElement(), Hashtable, Hashtable.elements(), Hashtable.keys(), Vector, Vector.elements() - */ +/// An object that implements the Enumeration interface generates a series of elements, one at a time. Successive calls to the nextElement method return successive elements of the series. +/// For example, to print all elements of a vector v: +/// Methods are provided to enumerate through the elements of a vector, the keys of a hashtable, and the values in a hashtable. +/// Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:nextElement(), Hashtable, Hashtable.elements(), Hashtable.keys(), Vector, Vector.elements() public interface Enumeration{ - /** - * Tests if this enumeration contains more elements. - */ + /// Tests if this enumeration contains more elements. abstract boolean hasMoreElements(); - /** - * Returns the next element of this enumeration if this enumeration object has at least one more element to provide. - */ + /// Returns the next element of this enumeration if this enumeration object has at least one more element to provide. abstract T nextElement(); } diff --git a/Ports/CLDC11/src/java/util/EventListener.java b/Ports/CLDC11/src/java/util/EventListener.java index b100f0c21a..62d0edf1c1 100644 --- a/Ports/CLDC11/src/java/util/EventListener.java +++ b/Ports/CLDC11/src/java/util/EventListener.java @@ -17,11 +17,11 @@ package java.util; -/** - * EventListener is the superclass of all event listener interfaces. - * - * @see EventObject - */ +/// EventListener is the superclass of all event listener interfaces. +/// +/// #### See also +/// +/// - EventObject public interface EventListener { /* empty */ } diff --git a/Ports/CLDC11/src/java/util/EventListenerProxy.java b/Ports/CLDC11/src/java/util/EventListenerProxy.java index 1e023f6cfd..2d3a243944 100644 --- a/Ports/CLDC11/src/java/util/EventListenerProxy.java +++ b/Ports/CLDC11/src/java/util/EventListenerProxy.java @@ -18,29 +18,26 @@ package java.util; -/** - * This abstract class provides a simple wrapper for objects of type {@code EventListener}. - */ +/// This abstract class provides a simple wrapper for objects of type `EventListener`. public abstract class EventListenerProxy implements EventListener { private final EventListener listener; - /** - * Creates a new {@code EventListener} proxy instance. - * - * @param listener - * the listener wrapped by this proxy. - */ + /// Creates a new `EventListener` proxy instance. + /// + /// #### Parameters + /// + /// - `listener`: the listener wrapped by this proxy. public EventListenerProxy(EventListener listener) { super(); this.listener = listener; } - /** - * Returns the wrapped {@code EventListener}. - * - * @return the wrapped {@code EventListener}. - */ + /// Returns the wrapped `EventListener`. + /// + /// #### Returns + /// + /// the wrapped `EventListener`. public EventListener getListener() { return listener; } diff --git a/Ports/CLDC11/src/java/util/HashMap.java b/Ports/CLDC11/src/java/util/HashMap.java index 302c727099..287731f960 100644 --- a/Ports/CLDC11/src/java/util/HashMap.java +++ b/Ports/CLDC11/src/java/util/HashMap.java @@ -17,10 +17,8 @@ package java.util; -/** - * HashMap is an implementation of Map. All optional operations (adding and - * removing) are supported. Keys and values can be any objects. - */ +/// HashMap is an implementation of Map. All optional operations (adding and +/// removing) are supported. Keys and values can be any objects. public class HashMap extends AbstractMap implements Map { private static final long serialVersionUID = 362498820763181265L; @@ -241,44 +239,48 @@ public Iterator> iterator() { } } - /** - * Create a new element array - * - * @param s - * @return Reference to the element array - */ + /// Create a new element array + /// + /// #### Parameters + /// + /// - `s` + /// + /// #### Returns + /// + /// Reference to the element array @SuppressWarnings("unchecked") Entry[] newElementArray(int s) { return new Entry[s]; } - /** - * Constructs a new empty {@code HashMap} instance. - */ + /// Constructs a new empty `HashMap` instance. public HashMap() { this(DEFAULT_SIZE); } - /** - * Constructs a new {@code HashMap} instance with the specified capacity. - * - * @param capacity - * the initial capacity of this hash map. - * @throws IllegalArgumentException - * when the capacity is less than zero. - */ + /// Constructs a new `HashMap` instance with the specified capacity. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of this hash map. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: when the capacity is less than zero. public HashMap(int capacity) { this(capacity, 0.75f); // default load factor of 0.75 } - /** - * Calculates the capacity of storage required for storing given number of - * elements - * - * @param x - * number of elements - * @return storage size - */ + /// Calculates the capacity of storage required for storing given number of + /// elements + /// + /// #### Parameters + /// + /// - `x`: number of elements + /// + /// #### Returns + /// + /// storage size private static final int calculateCapacity(int x) { if(x >= 1 << 30){ return 1 << 30; @@ -295,18 +297,20 @@ private static final int calculateCapacity(int x) { return x + 1; } - /** - * Constructs a new {@code HashMap} instance with the specified capacity and - * load factor. - * - * @param capacity - * the initial capacity of this hash map. - * @param loadFactor - * the initial load factor. - * @throws IllegalArgumentException - * when the capacity is less than zero or the load factor is - * less or equal to zero. - */ + /// Constructs a new `HashMap` instance with the specified capacity and + /// load factor. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of this hash map. + /// + /// - `loadFactor`: the initial load factor. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// when the capacity is less than zero or the load factor is + /// less or equal to zero. public HashMap(int capacity, float loadFactor) { if (capacity >= 0 && loadFactor > 0) { capacity = calculateCapacity(capacity); @@ -319,24 +323,24 @@ public HashMap(int capacity, float loadFactor) { } } - /** - * Constructs a new {@code HashMap} instance containing the mappings from - * the specified map. - * - * @param map - * the mappings to add. - */ + /// Constructs a new `HashMap` instance containing the mappings from + /// the specified map. + /// + /// #### Parameters + /// + /// - `map`: the mappings to add. public HashMap(Map map) { this(calculateCapacity(map.size())); putAllImpl(map); } - /** - * Removes all mappings from this hash map, leaving it empty. - * - * @see #isEmpty - * @see #size - */ + /// Removes all mappings from this hash map, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size @Override public void clear() { if (elementCount > 0) { @@ -346,35 +350,37 @@ public void clear() { } } - /** - * Computes the threshold for rehashing - */ + /// Computes the threshold for rehashing private void computeThreshold() { threshold = (int) (elementData.length * loadFactor); } - /** - * Returns whether this map contains the specified key. - * - * @param key - * the key to search for. - * @return {@code true} if this map contains the specified key, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified key, + /// `false` otherwise. @Override public boolean containsKey(Object key) { Entry m = getEntry(key); return m != null; } - /** - * Returns whether this map contains the specified value. - * - * @param value - * the value to search for. - * @return {@code true} if this map contains the specified value, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified value. + /// + /// #### Parameters + /// + /// - `value`: the value to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified value, + /// `false` otherwise. @Override public boolean containsValue(Object value) { if (value != null) { @@ -401,26 +407,28 @@ public boolean containsValue(Object value) { return false; } - /** - * Returns a set containing all of the mappings in this map. Each mapping is - * an instance of {@link Map.Entry}. As the set is backed by this map, - * changes in one will be reflected in the other. - * - * @return a set of the mappings. - */ + /// Returns a set containing all of the mappings in this map. Each mapping is + /// an instance of `Map.Entry`. As the set is backed by this map, + /// changes in one will be reflected in the other. + /// + /// #### Returns + /// + /// a set of the mappings. @Override public Set> entrySet() { return new HashMapEntrySet(this); } - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key, or {@code null} - * if no mapping for the specified key is found. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// @return the value of the mapping with the specified key, or `null` + /// if no mapping for the specified key is found. @Override public V get(Object key) { Entry m = getEntry(key); @@ -458,25 +466,28 @@ final Entry findNullKeyEntry() { return m; } - /** - * Returns whether this map is empty. - * - * @return {@code true} if this map has no elements, {@code false} - * otherwise. - * @see #size() - */ + /// Returns whether this map is empty. + /// + /// #### Returns + /// + /// @return `true` if this map has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size() @Override public boolean isEmpty() { return elementCount == 0; } - /** - * Returns a set of the keys contained in this map. The set is backed by - * this map so changes to one are reflected by the other. The set does not - * support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this map. The set is backed by + /// this map so changes to one are reflected by the other. The set does not + /// support adding. + /// + /// #### Returns + /// + /// a set of the keys. @Override public Set keySet() { if (keySet == null) { @@ -511,16 +522,18 @@ public Iterator iterator() { return keySet; } - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no such mapping. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no such mapping. @Override public V put(K key, V value) { return putImpl(key, value); @@ -569,16 +582,17 @@ Entry createHashedEntry(K key, int index, int hash) { return entry; } - /** - * Copies all the mappings in the specified map to this map. These mappings - * will replace all mappings that this map had for any of the keys currently - * in the given map. - * - * @param map - * the map to copy mappings from. - * @throws NullPointerException - * if {@code map} is {@code null}. - */ + /// Copies all the mappings in the specified map to this map. These mappings + /// will replace all mappings that this map had for any of the keys currently + /// in the given map. + /// + /// #### Parameters + /// + /// - `map`: the map to copy mappings from. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `map` is `null`. @Override public void putAll(Map map) { if (!map.isEmpty()) { @@ -621,14 +635,16 @@ void rehash() { rehash(elementData.length); } - /** - * Removes the mapping with the specified key from this map. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping or {@code null} if no mapping - * for the specified key was found. - */ + /// Removes the mapping with the specified key from this map. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping or `null` if no mapping + /// for the specified key was found. @Override public V remove(Object key) { Entry entry = removeEntry(key); @@ -690,35 +706,35 @@ final Entry removeEntry(Object key) { return entry; } - /** - * Returns the number of elements in this map. - * - * @return the number of elements in this map. - */ + /// Returns the number of elements in this map. + /// + /// #### Returns + /// + /// the number of elements in this map. @Override public int size() { return elementCount; } - /** - * Returns a collection of the values contained in this map. The collection - * is backed by this map so changes to one are reflected by the other. The - * collection supports remove, removeAll, retainAll and clear operations, - * and it does not support add or addAll operations. - *

- * This method returns a collection which is the subclass of - * AbstractCollection. The iterator method of this subclass returns a - * "wrapper object" over the iterator of map's entrySet(). The {@code size} - * method wraps the map's size method and the {@code contains} method wraps - * the map's containsValue method. - *

- * The collection is created when this method is called for the first time - * and returned in response to all subsequent calls. This method may return - * different collections when multiple concurrent calls occur, since no - * synchronization is performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a collection of the values contained in this map. The collection + /// is backed by this map so changes to one are reflected by the other. The + /// collection supports remove, removeAll, retainAll and clear operations, + /// and it does not support add or addAll operations. + /// + /// This method returns a collection which is the subclass of + /// AbstractCollection. The iterator method of this subclass returns a + /// "wrapper object" over the iterator of map's entrySet(). The `size` + /// method wraps the map's size method and the `contains` method wraps + /// the map's containsValue method. + /// + /// The collection is created when this method is called for the first time + /// and returned in response to all subsequent calls. This method may return + /// different collections when multiple concurrent calls occur, since no + /// synchronization is performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. @Override public Collection values() { if (valuesCollection == null) { diff --git a/Ports/CLDC11/src/java/util/HashSet.java b/Ports/CLDC11/src/java/util/HashSet.java index bfa1033963..81326f8ea4 100644 --- a/Ports/CLDC11/src/java/util/HashSet.java +++ b/Ports/CLDC11/src/java/util/HashSet.java @@ -17,51 +17,44 @@ package java.util; -/** - * HashSet is an implementation of a Set. All optional operations (adding and - * removing) are supported. The elements can be any objects. - */ +/// HashSet is an implementation of a Set. All optional operations (adding and +/// removing) are supported. The elements can be any objects. public class HashSet extends AbstractSet implements Set { transient HashMap> backingMap; - /** - * Constructs a new empty instance of {@code HashSet}. - */ + /// Constructs a new empty instance of `HashSet`. public HashSet() { this(new HashMap>()); } - /** - * Constructs a new instance of {@code HashSet} with the specified capacity. - * - * @param capacity - * the initial capacity of this {@code HashSet}. - */ + /// Constructs a new instance of `HashSet` with the specified capacity. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of this `HashSet`. public HashSet(int capacity) { this(new HashMap>(capacity)); } - /** - * Constructs a new instance of {@code HashSet} with the specified capacity - * and load factor. - * - * @param capacity - * the initial capacity. - * @param loadFactor - * the initial load factor. - */ + /// Constructs a new instance of `HashSet` with the specified capacity + /// and load factor. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity. + /// + /// - `loadFactor`: the initial load factor. public HashSet(int capacity, float loadFactor) { this(new HashMap>(capacity, loadFactor)); } - /** - * Constructs a new instance of {@code HashSet} containing the unique - * elements in the specified collection. - * - * @param collection - * the collection of elements to add. - */ + /// Constructs a new instance of `HashSet` containing the unique + /// elements in the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. public HashSet(Collection collection) { this(new HashMap>(collection.size() < 6 ? 11 : collection .size() * 2)); @@ -75,84 +68,97 @@ public HashSet(Collection collection) { this.backingMap = backingMap; } - /** - * Adds the specified object to this {@code HashSet} if not already present. - * - * @param object - * the object to add. - * @return {@code true} when this {@code HashSet} did not already contain - * the object, {@code false} otherwise - */ + /// Adds the specified object to this `HashSet` if not already present. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// @return `true` when this `HashSet` did not already contain + /// the object, `false` otherwise @Override public boolean add(E object) { return backingMap.put(object, this) == null; } - /** - * Removes all elements from this {@code HashSet}, leaving it empty. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `HashSet`, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size @Override public void clear() { backingMap.clear(); } - /** - * Searches this {@code HashSet} for the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if {@code object} is an element of this - * {@code HashSet}, {@code false} otherwise. - */ + /// Searches this `HashSet` for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if `object` is an element of this + /// `HashSet`, `false` otherwise. @Override public boolean contains(Object object) { return backingMap.containsKey(object); } - /** - * Returns true if this {@code HashSet} has no elements, false otherwise. - * - * @return {@code true} if this {@code HashSet} has no elements, - * {@code false} otherwise. - * @see #size - */ + /// Returns true if this `HashSet` has no elements, false otherwise. + /// + /// #### Returns + /// + /// @return `true` if this `HashSet` has no elements, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #size @Override public boolean isEmpty() { return backingMap.isEmpty(); } - /** - * Returns an Iterator on the elements of this {@code HashSet}. - * - * @return an Iterator on the elements of this {@code HashSet}. - * @see Iterator - */ + /// Returns an Iterator on the elements of this `HashSet`. + /// + /// #### Returns + /// + /// an Iterator on the elements of this `HashSet`. + /// + /// #### See also + /// + /// - Iterator @Override public Iterator iterator() { return backingMap.keySet().iterator(); } - /** - * Removes the specified object from this {@code HashSet}. - * - * @param object - * the object to remove. - * @return {@code true} if the object was removed, {@code false} otherwise. - */ + /// Removes the specified object from this `HashSet`. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// `true` if the object was removed, `false` otherwise. @Override public boolean remove(Object object) { return backingMap.remove(object) != null; } - /** - * Returns the number of elements in this {@code HashSet}. - * - * @return the number of elements in this {@code HashSet}. - */ + /// Returns the number of elements in this `HashSet`. + /// + /// #### Returns + /// + /// the number of elements in this `HashSet`. @Override public int size() { return backingMap.size(); diff --git a/Ports/CLDC11/src/java/util/Hashtable.java b/Ports/CLDC11/src/java/util/Hashtable.java index c54d0c3be2..206fb2b6f8 100644 --- a/Ports/CLDC11/src/java/util/Hashtable.java +++ b/Ports/CLDC11/src/java/util/Hashtable.java @@ -18,19 +18,22 @@ package java.util; -/** - * Hashtable associates keys with values. Both keys and values cannot be null. - * The size of the Hashtable is the number of key/value pairs it contains. The - * capacity is the number of key/value pairs the Hashtable can hold. The load - * factor is a float value which determines how full the Hashtable gets before - * expanding the capacity. If the load factor of the Hashtable is exceeded, the - * capacity is doubled. - * - * @see Enumeration - * @see java.io.Serializable - * @see java.lang.Object#equals - * @see java.lang.Object#hashCode - */ +/// Hashtable associates keys with values. Both keys and values cannot be null. +/// The size of the Hashtable is the number of key/value pairs it contains. The +/// capacity is the number of key/value pairs the Hashtable can hold. The load +/// factor is a float value which determines how full the Hashtable gets before +/// expanding the capacity. If the load factor of the Hashtable is exceeded, the +/// capacity is doubled. +/// +/// #### See also +/// +/// - Enumeration +/// +/// - java.io.Serializable +/// +/// - java.lang.Object#equals +/// +/// - java.lang.Object#hashCode public class Hashtable extends Dictionary implements Map { transient int elementCount; @@ -207,21 +210,18 @@ public void remove() { } } - /** - * Constructs a new {@code Hashtable} using the default capacity and load - * factor. - */ + /// Constructs a new `Hashtable` using the default capacity and load + /// factor. public Hashtable() { this(11); } - /** - * Constructs a new {@code Hashtable} using the specified capacity and the - * default load factor. - * - * @param capacity - * the initial capacity. - */ + /// Constructs a new `Hashtable` using the specified capacity and the + /// default load factor. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity. public Hashtable(int capacity) { if (capacity >= 0) { elementCount = 0; @@ -234,15 +234,14 @@ public Hashtable(int capacity) { } } - /** - * Constructs a new {@code Hashtable} using the specified capacity and load - * factor. - * - * @param capacity - * the initial capacity. - * @param loadFactor - * the initial load factor. - */ + /// Constructs a new `Hashtable` using the specified capacity and load + /// factor. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity. + /// + /// - `loadFactor`: the initial load factor. public Hashtable(int capacity, float loadFactor) { if (capacity >= 0 && loadFactor > 0) { elementCount = 0; @@ -255,13 +254,12 @@ public Hashtable(int capacity, float loadFactor) { } } - /** - * Constructs a new instance of {@code Hashtable} containing the mappings - * from the specified map. - * - * @param map - * the mappings to add. - */ + /// Constructs a new instance of `Hashtable` containing the mappings + /// from the specified map. + /// + /// #### Parameters + /// + /// - `map`: the mappings to add. public Hashtable(Map map) { this(map.size() < 6 ? 11 : (map.size() * 4 / 3) + 11); putAll(map); @@ -272,13 +270,14 @@ private Entry[] newElementArray(int size) { return new Entry[size]; } - /** - * Removes all key/value pairs from this {@code Hashtable}, leaving the - * size zero and the capacity unchanged. - * - * @see #isEmpty - * @see #size - */ + /// Removes all key/value pairs from this `Hashtable`, leaving the + /// size zero and the capacity unchanged. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size public synchronized void clear() { elementCount = 0; Arrays.fill(elementData, null); @@ -290,17 +289,23 @@ private void computeMaxSize() { threshold = (int) (elementData.length * loadFactor); } - /** - * Returns true if this {@code Hashtable} contains the specified object as - * the value of at least one of the key/value pairs. - * - * @param value - * the object to look for as a value in this {@code Hashtable}. - * @return {@code true} if object is a value in this {@code Hashtable}, - * {@code false} otherwise. - * @see #containsKey - * @see java.lang.Object#equals - */ + /// Returns true if this `Hashtable` contains the specified object as + /// the value of at least one of the key/value pairs. + /// + /// #### Parameters + /// + /// - `value`: the object to look for as a value in this `Hashtable`. + /// + /// #### Returns + /// + /// @return `true` if object is a value in this `Hashtable`, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #containsKey + /// + /// - java.lang.Object#equals public synchronized boolean contains(Object value) { if (value == null) { throw new NullPointerException(); @@ -318,43 +323,56 @@ public synchronized boolean contains(Object value) { return false; } - /** - * Returns true if this {@code Hashtable} contains the specified object as a - * key of one of the key/value pairs. - * - * @param key - * the object to look for as a key in this {@code Hashtable}. - * @return {@code true} if object is a key in this {@code Hashtable}, - * {@code false} otherwise. - * @see #contains - * @see java.lang.Object#equals - */ + /// Returns true if this `Hashtable` contains the specified object as a + /// key of one of the key/value pairs. + /// + /// #### Parameters + /// + /// - `key`: the object to look for as a key in this `Hashtable`. + /// + /// #### Returns + /// + /// @return `true` if object is a key in this `Hashtable`, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #contains + /// + /// - java.lang.Object#equals public synchronized boolean containsKey(Object key) { return getEntry(key) != null; } - /** - * Searches this {@code Hashtable} for the specified value. - * - * @param value - * the object to search for. - * @return {@code true} if {@code value} is a value of this - * {@code Hashtable}, {@code false} otherwise. - */ + /// Searches this `Hashtable` for the specified value. + /// + /// #### Parameters + /// + /// - `value`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if `value` is a value of this + /// `Hashtable`, `false` otherwise. public boolean containsValue(Object value) { return contains(value); } - /** - * Returns an enumeration on the values of this {@code Hashtable}. The - * results of the Enumeration may be affected if the contents of this - * {@code Hashtable} are modified. - * - * @return an enumeration of the values of this {@code Hashtable}. - * @see #keys - * @see #size - * @see Enumeration - */ + /// Returns an enumeration on the values of this `Hashtable`. The + /// results of the Enumeration may be affected if the contents of this + /// `Hashtable` are modified. + /// + /// #### Returns + /// + /// an enumeration of the values of this `Hashtable`. + /// + /// #### See also + /// + /// - #keys + /// + /// - #size + /// + /// - Enumeration @Override @SuppressWarnings("unchecked") public synchronized java.util.Enumeration elements() { @@ -368,14 +386,14 @@ public V get(MapEntry entry) { }, true); } - /** - * Returns a set of the mappings contained in this {@code Hashtable}. Each - * element in the set is a {@link Map.Entry}. The set is backed by this - * {@code Hashtable} so changes to one are reflected by the other. The set - * does not support adding. - * - * @return a set of the mappings. - */ + /// Returns a set of the mappings contained in this `Hashtable`. Each + /// element in the set is a `Map.Entry`. The set is backed by this + /// `Hashtable` so changes to one are reflected by the other. The set + /// does not support adding. + /// + /// #### Returns + /// + /// a set of the mappings. public Set> entrySet() { return new Collections.SynchronizedSet>( new AbstractSet>() { @@ -421,17 +439,22 @@ public Map.Entry get( }, this); } - /** - * Compares this {@code Hashtable} with the specified object and indicates - * if they are equal. In order to be equal, {@code object} must be an - * instance of Map and contain the same key/value pairs. - * - * @param object - * the object to compare with this object. - * @return {@code true} if the specified object is equal to this Map, - * {@code false} otherwise. - * @see #hashCode - */ + /// Compares this `Hashtable` with the specified object and indicates + /// if they are equal. In order to be equal, `object` must be an + /// instance of Map and contain the same key/value pairs. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object. + /// + /// #### Returns + /// + /// @return `true` if the specified object is equal to this Map, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #hashCode @Override public synchronized boolean equals(Object object) { if (this == object) { @@ -456,16 +479,21 @@ public synchronized boolean equals(Object object) { return false; } - /** - * Returns the value associated with the specified key in this - * {@code Hashtable}. - * - * @param key - * the key of the value returned. - * @return the value associated with the specified key, or {@code null} if - * the specified key does not exist. - * @see #put - */ + /// Returns the value associated with the specified key in this + /// `Hashtable`. + /// + /// #### Parameters + /// + /// - `key`: the key of the value returned. + /// + /// #### Returns + /// + /// @return the value associated with the specified key, or `null` if + /// the specified key does not exist. + /// + /// #### See also + /// + /// - #put @Override public synchronized V get(Object key) { int hash = key.hashCode(); @@ -514,28 +542,36 @@ public synchronized int hashCode() { return result; } - /** - * Returns true if this {@code Hashtable} has no key/value pairs. - * - * @return {@code true} if this {@code Hashtable} has no key/value pairs, - * {@code false} otherwise. - * @see #size - */ + /// Returns true if this `Hashtable` has no key/value pairs. + /// + /// #### Returns + /// + /// @return `true` if this `Hashtable` has no key/value pairs, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #size @Override public synchronized boolean isEmpty() { return elementCount == 0; } - /** - * Returns an enumeration on the keys of this {@code Hashtable} instance. - * The results of the enumeration may be affected if the contents of this - * {@code Hashtable} are modified. - * - * @return an enumeration of the keys of this {@code Hashtable}. - * @see #elements - * @see #size - * @see Enumeration - */ + /// Returns an enumeration on the keys of this `Hashtable` instance. + /// The results of the enumeration may be affected if the contents of this + /// `Hashtable` are modified. + /// + /// #### Returns + /// + /// an enumeration of the keys of this `Hashtable`. + /// + /// #### See also + /// + /// - #elements + /// + /// - #size + /// + /// - Enumeration @Override @SuppressWarnings("unchecked") public synchronized java.util.Enumeration keys() { @@ -549,13 +585,13 @@ public K get(MapEntry entry) { }, true); } - /** - * Returns a set of the keys contained in this {@code Hashtable}. The set - * is backed by this {@code Hashtable} so changes to one are reflected by - * the other. The set does not support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this `Hashtable`. The set + /// is backed by this `Hashtable` so changes to one are reflected by + /// the other. The set does not support adding. + /// + /// #### Returns + /// + /// a set of the keys. public Set keySet() { return new Collections.SynchronizedSet(new AbstractSet() { @Override @@ -674,22 +710,30 @@ public void remove() { } } - /** - * Associate the specified value with the specified key in this - * {@code Hashtable}. If the key already exists, the old value is replaced. - * The key and value cannot be null. - * - * @param key - * the key to add. - * @param value - * the value to add. - * @return the old value associated with the specified key, or {@code null} - * if the key did not exist. - * @see #elements - * @see #get - * @see #keys - * @see java.lang.Object#equals - */ + /// Associate the specified value with the specified key in this + /// `Hashtable`. If the key already exists, the old value is replaced. + /// The key and value cannot be null. + /// + /// #### Parameters + /// + /// - `key`: the key to add. + /// + /// - `value`: the value to add. + /// + /// #### Returns + /// + /// @return the old value associated with the specified key, or `null` + /// if the key did not exist. + /// + /// #### See also + /// + /// - #elements + /// + /// - #get + /// + /// - #keys + /// + /// - java.lang.Object#equals @Override public synchronized V put(K key, V value) { if (key != null && value != null) { @@ -723,12 +767,11 @@ public synchronized V put(K key, V value) { throw new NullPointerException(); } - /** - * Copies every mapping to this {@code Hashtable} from the specified map. - * - * @param map - * the map to copy mappings from. - */ + /// Copies every mapping to this `Hashtable` from the specified map. + /// + /// #### Parameters + /// + /// - `map`: the map to copy mappings from. public synchronized void putAll(Map map) { Iterator it = map.entrySet().iterator(); while(it.hasNext()) { @@ -737,10 +780,8 @@ public synchronized void putAll(Map map) { } } - /** - * Increases the capacity of this {@code Hashtable}. This method is called - * when the size of this {@code Hashtable} exceeds the load factor. - */ + /// Increases the capacity of this `Hashtable`. This method is called + /// when the size of this `Hashtable` exceeds the load factor. protected void rehash() { int length = (elementData.length << 1) + 1; if (length == 0) { @@ -771,17 +812,23 @@ protected void rehash() { computeMaxSize(); } - /** - * Removes the key/value pair with the specified key from this - * {@code Hashtable}. - * - * @param key - * the key to remove. - * @return the value associated with the specified key, or {@code null} if - * the specified key did not exist. - * @see #get - * @see #put - */ + /// Removes the key/value pair with the specified key from this + /// `Hashtable`. + /// + /// #### Parameters + /// + /// - `key`: the key to remove. + /// + /// #### Returns + /// + /// @return the value associated with the specified key, or `null` if + /// the specified key did not exist. + /// + /// #### See also + /// + /// - #get + /// + /// - #put @Override public synchronized V remove(Object key) { int hash = key.hashCode(); @@ -807,23 +854,27 @@ public synchronized V remove(Object key) { return null; } - /** - * Returns the number of key/value pairs in this {@code Hashtable}. - * - * @return the number of key/value pairs in this {@code Hashtable}. - * @see #elements - * @see #keys - */ + /// Returns the number of key/value pairs in this `Hashtable`. + /// + /// #### Returns + /// + /// the number of key/value pairs in this `Hashtable`. + /// + /// #### See also + /// + /// - #elements + /// + /// - #keys @Override public synchronized int size() { return elementCount; } - /** - * Returns the string representation of this {@code Hashtable}. - * - * @return the string representation of this {@code Hashtable}. - */ + /// Returns the string representation of this `Hashtable`. + /// + /// #### Returns + /// + /// the string representation of this `Hashtable`. @Override public synchronized String toString() { if (isEmpty()) { @@ -860,13 +911,13 @@ public synchronized String toString() { return buffer.toString(); } - /** - * Returns a collection of the values contained in this {@code Hashtable}. - * The collection is backed by this {@code Hashtable} so changes to one are - * reflected by the other. The collection does not support adding. - * - * @return a collection of the values. - */ + /// Returns a collection of the values contained in this `Hashtable`. + /// The collection is backed by this `Hashtable` so changes to one are + /// reflected by the other. The collection does not support adding. + /// + /// #### Returns + /// + /// a collection of the values. public Collection values() { return new Collections.SynchronizedCollection( new AbstractCollection() { diff --git a/Ports/CLDC11/src/java/util/IdentityHashMap.java b/Ports/CLDC11/src/java/util/IdentityHashMap.java index c1588e2dea..a22124e8f5 100644 --- a/Ports/CLDC11/src/java/util/IdentityHashMap.java +++ b/Ports/CLDC11/src/java/util/IdentityHashMap.java @@ -17,24 +17,23 @@ package java.util; -/** - * IdentityHashMap is a variant on HashMap which tests equality by reference - * instead of equality by value. Basically, keys and values are compared for - * equality by checking if their references are equal rather than by calling the - * "equals" function. - *

- * Note: This class intentionally violates the general contract of {@code - * Map}'s on comparing objects by their {@code equals} method. - *

- * IdentityHashMap uses open addressing (linear probing in particular) for - * collision resolution. This is different from HashMap which uses Chaining. - *

- * Like HashMap, IdentityHashMap is not thread safe, so access by multiple - * threads must be synchronized by an external mechanism such as - * Collections.synchronizedMap. - * - * @since 1.4 - */ +/// IdentityHashMap is a variant on HashMap which tests equality by reference +/// instead of equality by value. Basically, keys and values are compared for +/// equality by checking if their references are equal rather than by calling the +/// "equals" function. +/// +/// **Note: This class intentionally violates the general contract of `Map`'s on comparing objects by their `equals` method.** +/// +/// IdentityHashMap uses open addressing (linear probing in particular) for +/// collision resolution. This is different from HashMap which uses Chaining. +/// +/// Like HashMap, IdentityHashMap is not thread safe, so access by multiple +/// threads must be synchronized by an external mechanism such as +/// Collections.synchronizedMap. +/// +/// #### Since +/// +/// 1.4 public class IdentityHashMap extends AbstractMap implements Map { @@ -224,20 +223,18 @@ public Map.Entry get(MapEntry entry) { } } - /** - * Creates an IdentityHashMap with default expected maximum size. - */ + /// Creates an IdentityHashMap with default expected maximum size. public IdentityHashMap() { this(DEFAULT_MAX_SIZE); } - /** - * Creates an IdentityHashMap with the specified maximum size parameter. - * - * @param maxSize - * The estimated maximum number of entries that will be put in - * this map. - */ + /// Creates an IdentityHashMap with the specified maximum size parameter. + /// + /// #### Parameters + /// + /// - `maxSize`: @param maxSize + /// The estimated maximum number of entries that will be put in + /// this map. public IdentityHashMap(int maxSize) { if (maxSize >= 0) { this.size = 0; @@ -261,23 +258,24 @@ private int computeElementArraySize() { return arraySize < 0 ? -arraySize : arraySize; } - /** - * Create a new element array - * - * @param s - * the number of elements - * @return Reference to the element array - */ + /// Create a new element array + /// + /// #### Parameters + /// + /// - `s`: the number of elements + /// + /// #### Returns + /// + /// Reference to the element array private Object[] newElementArray(int s) { return new Object[s]; } - /** - * Creates an IdentityHashMap using the given map as initial values. - * - * @param map - * A map of (key,value) pairs to copy into the IdentityHashMap. - */ + /// Creates an IdentityHashMap using the given map as initial values. + /// + /// #### Parameters + /// + /// - `map`: A map of (key,value) pairs to copy into the IdentityHashMap. public IdentityHashMap(Map map) { this(map.size() < 6 ? 11 : map.size() * 2); putAllImpl(map); @@ -288,12 +286,13 @@ private V massageValue(Object value) { return (V) ((value == NULL_OBJECT) ? null : value); } - /** - * Removes all elements from this map, leaving it empty. - * - * @see #isEmpty() - * @see #size() - */ + /// Removes all elements from this map, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty() + /// + /// - #size() @Override public void clear() { size = 0; @@ -303,14 +302,16 @@ public void clear() { modCount++; } - /** - * Returns whether this map contains the specified key. - * - * @param key - * the key to search for. - * @return {@code true} if this map contains the specified key, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified key, + /// `false` otherwise. @Override public boolean containsKey(Object key) { if (key == null) { @@ -321,14 +322,16 @@ public boolean containsKey(Object key) { return elementData[index] == key; } - /** - * Returns whether this map contains the specified value. - * - * @param value - * the value to search for. - * @return {@code true} if this map contains the specified value, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified value. + /// + /// #### Parameters + /// + /// - `value`: the value to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified value, + /// `false` otherwise. @Override public boolean containsValue(Object value) { if (value == null) { @@ -343,13 +346,15 @@ public boolean containsValue(Object value) { return false; } - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// the value of the mapping with the specified key. @Override public V get(Object key) { if (key == null) { @@ -379,10 +384,8 @@ private IdentityHashMapEntry getEntry(Object key) { return null; } - /** - * Convenience method for getting the IdentityHashMapEntry without the - * NULL_OBJECT elements - */ + /// Convenience method for getting the IdentityHashMapEntry without the + /// NULL_OBJECT elements @SuppressWarnings("unchecked") private IdentityHashMapEntry getEntry(int index) { Object key = elementData[index]; @@ -398,10 +401,8 @@ private IdentityHashMapEntry getEntry(int index) { return new IdentityHashMapEntry((K) key, (V) value); } - /** - * Returns the index where the key is found at, or the index of the next - * empty spot if the key is not found in this table. - */ + /// Returns the index where the key is found at, or the index of the next + /// empty spot if the key is not found in this table. private int findIndex(Object key, Object[] array) { int length = array.length; int index = getModuloHash(key, length); @@ -423,16 +424,18 @@ private int getModuloHash(Object key, int length) { return ((System.identityHashCode(key) & 0x7FFFFFFF) % (length / 2)) * 2; } - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no such mapping. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no such mapping. @Override public V put(K key, V value) { Object _key = key; @@ -467,16 +470,17 @@ public V put(K key, V value) { return massageValue(result); } - /** - * Copies all the mappings in the specified map to this map. These mappings - * will replace all mappings that this map had for any of the keys currently - * in the given map. - * - * @param map - * the map to copy mappings from. - * @throws NullPointerException - * if {@code map} is {@code null}. - */ + /// Copies all the mappings in the specified map to this map. These mappings + /// will replace all mappings that this map had for any of the keys currently + /// in the given map. + /// + /// #### Parameters + /// + /// - `map`: the map to copy mappings from. + /// + /// #### Throws + /// + /// - `NullPointerException`: if `map` is `null`. @Override public void putAll(Map map) { putAllImpl(map); @@ -505,14 +509,16 @@ private void computeMaxSize() { threshold = (int) ((long) (elementData.length / 2) * loadFactor / 10000); } - /** - * Removes the mapping with the specified key from this map. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping, or {@code null} if no mapping - * for the specified key was found. - */ + /// Removes the mapping with the specified key from this map. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping, or `null` if no mapping + /// for the specified key was found. @Override public V remove(Object key) { if (key == null) { @@ -565,25 +571,25 @@ public V remove(Object key) { return massageValue(result); } - /** - * Returns a set containing all of the mappings in this map. Each mapping is - * an instance of {@link Map.Entry}. As the set is backed by this map, - * changes in one will be reflected in the other. - * - * @return a set of the mappings. - */ + /// Returns a set containing all of the mappings in this map. Each mapping is + /// an instance of `Map.Entry`. As the set is backed by this map, + /// changes in one will be reflected in the other. + /// + /// #### Returns + /// + /// a set of the mappings. @Override public Set> entrySet() { return new IdentityHashMapEntrySet(this); } - /** - * Returns a set of the keys contained in this map. The set is backed by - * this map so changes to one are reflected by the other. The set does not - * support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this map. The set is backed by + /// this map so changes to one are reflected by the other. The set does not + /// support adding. + /// + /// #### Returns + /// + /// a set of the keys. @Override public Set keySet() { if (keySet == null) { @@ -626,25 +632,25 @@ public K get(MapEntry entry) { return keySet; } - /** - * Returns a collection of the values contained in this map. The collection - * is backed by this map so changes to one are reflected by the other. The - * collection supports remove, removeAll, retainAll and clear operations, - * and it does not support add or addAll operations. - *

- * This method returns a collection which is the subclass of - * AbstractCollection. The iterator method of this subclass returns a - * "wrapper object" over the iterator of map's entrySet(). The {@code size} - * method wraps the map's size method and the {@code contains} method wraps - * the map's containsValue method. - *

- * The collection is created when this method is called for the first time - * and returned in response to all subsequent calls. This method may return - * different collections when multiple concurrent calls occur, since no - * synchronization is performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a collection of the values contained in this map. The collection + /// is backed by this map so changes to one are reflected by the other. The + /// collection supports remove, removeAll, retainAll and clear operations, + /// and it does not support add or addAll operations. + /// + /// This method returns a collection which is the subclass of + /// AbstractCollection. The iterator method of this subclass returns a + /// "wrapper object" over the iterator of map's entrySet(). The `size` + /// method wraps the map's size method and the `contains` method wraps + /// the map's containsValue method. + /// + /// The collection is created when this method is called for the first time + /// and returned in response to all subsequent calls. This method may return + /// different collections when multiple concurrent calls occur, since no + /// synchronization is performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. @Override public Collection values() { if (valuesCollection == null) { @@ -690,18 +696,20 @@ public boolean remove(Object object) { return valuesCollection; } - /** - * Compares this map with other objects. This map is equal to another map is - * it represents the same set of mappings. With this map, two mappings are - * the same if both the key and the value are equal by reference. When - * compared with a map that is not an IdentityHashMap, the equals method is - * neither necessarily symmetric (a.equals(b) implies b.equals(a)) nor - * transitive (a.equals(b) and b.equals(c) implies a.equals(c)). - * - * @param object - * the object to compare to. - * @return whether the argument object is equal to this object. - */ + /// Compares this map with other objects. This map is equal to another map is + /// it represents the same set of mappings. With this map, two mappings are + /// the same if both the key and the value are equal by reference. When + /// compared with a map that is not an IdentityHashMap, the equals method is + /// neither necessarily symmetric (a.equals(b) implies b.equals(a)) nor + /// transitive (a.equals(b) and b.equals(c) implies a.equals(c)). + /// + /// #### Parameters + /// + /// - `object`: the object to compare to. + /// + /// #### Returns + /// + /// whether the argument object is equal to this object. @Override public boolean equals(Object object) { /* @@ -729,23 +737,26 @@ public boolean equals(Object object) { return false; } - /** - * Returns whether this IdentityHashMap has no elements. - * - * @return {@code true} if this IdentityHashMap has no elements, - * {@code false} otherwise. - * @see #size() - */ + /// Returns whether this IdentityHashMap has no elements. + /// + /// #### Returns + /// + /// @return `true` if this IdentityHashMap has no elements, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #size() @Override public boolean isEmpty() { return size == 0; } - /** - * Returns the number of mappings in this IdentityHashMap. - * - * @return the number of mappings in this IdentityHashMap. - */ + /// Returns the number of mappings in this IdentityHashMap. + /// + /// #### Returns + /// + /// the number of mappings in this IdentityHashMap. @Override public int size() { return size; diff --git a/Ports/CLDC11/src/java/util/Iterator.java b/Ports/CLDC11/src/java/util/Iterator.java index 6ebae04365..d3323bfa05 100644 --- a/Ports/CLDC11/src/java/util/Iterator.java +++ b/Ports/CLDC11/src/java/util/Iterator.java @@ -17,50 +17,57 @@ package java.util; -/** - * An {@code Iterator} is used to sequence over a collection of objects. - * Conceptually, an iterator is always positioned between two elements of a - * collection. A fresh iterator is always positioned in front of the first - * element. - * - * If a collection has been changed since its creation, methods {@code next} and - * {@code hasNext()} may throw a {@code ConcurrentModificationException}. - * Iterators with this behavior are called fail-fast iterators. - * - * @param - * the type of object returned by the iterator. - */ +/// An `Iterator` is used to sequence over a collection of objects. +/// Conceptually, an iterator is always positioned between two elements of a +/// collection. A fresh iterator is always positioned in front of the first +/// element. +/// +/// If a collection has been changed since its creation, methods `next` and +/// `hasNext()` may throw a `ConcurrentModificationException`. +/// Iterators with this behavior are called fail-fast iterators. +/// +/// @param +/// the type of object returned by the iterator. public interface Iterator { - /** - * Returns whether there are more elements to iterate, i.e. whether the - * iterator is positioned in front of an element. - * - * @return {@code true} if there are more elements, {@code false} otherwise. - * @see #next - */ + /// Returns whether there are more elements to iterate, i.e. whether the + /// iterator is positioned in front of an element. + /// + /// #### Returns + /// + /// `true` if there are more elements, `false` otherwise. + /// + /// #### See also + /// + /// - #next public boolean hasNext(); - /** - * Returns the next object in the iteration, i.e. returns the element in - * front of the iterator and advances the iterator by one position. - * - * @return the next object. - * @throws NoSuchElementException - * if there are no more elements. - * @see #hasNext - */ + /// Returns the next object in the iteration, i.e. returns the element in + /// front of the iterator and advances the iterator by one position. + /// + /// #### Returns + /// + /// the next object. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there are no more elements. + /// + /// #### See also + /// + /// - #hasNext public E next(); - /** - * Removes the last object returned by {@code next} from the collection. - * This method can only be called once after {@code next} was called. - * - * @throws UnsupportedOperationException - * if removing is not supported by the collection being - * iterated. - * @throws IllegalStateException - * if {@code next} has not been called, or {@code remove} has - * already been called after the last call to {@code next}. - */ + /// Removes the last object returned by `next` from the collection. + /// This method can only be called once after `next` was called. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: @throws UnsupportedOperationException + /// if removing is not supported by the collection being + /// iterated. + /// + /// - `IllegalStateException`: @throws IllegalStateException + /// if `next` has not been called, or `remove` has + /// already been called after the last call to `next`. public void remove(); } diff --git a/Ports/CLDC11/src/java/util/LinkedHashMap.java b/Ports/CLDC11/src/java/util/LinkedHashMap.java index 47eb472993..260d1549cc 100644 --- a/Ports/CLDC11/src/java/util/LinkedHashMap.java +++ b/Ports/CLDC11/src/java/util/LinkedHashMap.java @@ -17,37 +17,37 @@ package java.util; -/** - * LinkedHashMap is a variant of HashMap. Its entries are kept in a - * doubly-linked list. The iteration order is, by default, the order in which - * keys were inserted. Reinserting an already existing key doesn't change the - * order. A key is existing if a call to {@code containsKey} would return true. - *

- * If the three argument constructor is used, and {@code order} is specified as - * {@code true}, the iteration will be in the order that entries were accessed. - * The access order gets affected by put(), get(), putAll() operations, but not - * by operations on the collection views. - *

- * Null elements are allowed, and all the optional map operations are supported. - *

- * Note: The implementation of {@code LinkedHashMap} is not synchronized. - * If one thread of several threads accessing an instance modifies the map - * structurally, access to the map needs to be synchronized. For - * insertion-ordered instances a structural modification is an operation that - * removes or adds an entry. Access-ordered instances also are structurally - * modified by put(), get() and putAll() since these methods change the order of - * the entries. Changes in the value of an entry are not structural changes. - *

- * The Iterator that can be created by calling the {@code iterator} method - * throws a {@code ConcurrentModificationException} if the map is structurally - * changed while an iterator is used to iterate over the elements. Only the - * {@code remove} method that is provided by the iterator allows for removal of - * elements during iteration. It is not possible to guarantee that this - * mechanism works in all cases of unsynchronized concurrent modification. It - * should only be used for debugging purposes. - * - * @since 1.4 - */ +/// LinkedHashMap is a variant of HashMap. Its entries are kept in a +/// doubly-linked list. The iteration order is, by default, the order in which +/// keys were inserted. Reinserting an already existing key doesn't change the +/// order. A key is existing if a call to `containsKey` would return true. +/// +/// If the three argument constructor is used, and `order` is specified as +/// `true`, the iteration will be in the order that entries were accessed. +/// The access order gets affected by put(), get(), putAll() operations, but not +/// by operations on the collection views. +/// +/// Null elements are allowed, and all the optional map operations are supported. +/// +/// **Note:** The implementation of `LinkedHashMap` is not synchronized. +/// If one thread of several threads accessing an instance modifies the map +/// structurally, access to the map needs to be synchronized. For +/// insertion-ordered instances a structural modification is an operation that +/// removes or adds an entry. Access-ordered instances also are structurally +/// modified by put(), get() and putAll() since these methods change the order of +/// the entries. Changes in the value of an entry are not structural changes. +/// +/// The Iterator that can be created by calling the `iterator` method +/// throws a `ConcurrentModificationException` if the map is structurally +/// changed while an iterator is used to iterate over the elements. Only the +/// `remove` method that is provided by the iterator allows for removal of +/// elements during iteration. It is not possible to guarantee that this +/// mechanism works in all cases of unsynchronized concurrent modification. It +/// should only be used for debugging purposes. +/// +/// #### Since +/// +/// 1.4 public class LinkedHashMap extends HashMap implements Map { private static final long serialVersionUID = 3801124242820219131L; @@ -56,42 +56,43 @@ public class LinkedHashMap extends HashMap implements Map { transient private LinkedHashMapEntry head, tail; - /** - * Constructs a new empty {@code LinkedHashMap} instance. - */ + /// Constructs a new empty `LinkedHashMap` instance. public LinkedHashMap() { super(); accessOrder = false; head = null; } - /** - * Constructs a new {@code LinkedHashMap} instance with the specified - * capacity. - * - * @param s - * the initial capacity of this map. - * @throws IllegalArgumentException - * if the capacity is less than zero. - */ + /// Constructs a new `LinkedHashMap` instance with the specified + /// capacity. + /// + /// #### Parameters + /// + /// - `s`: the initial capacity of this map. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if the capacity is less than zero. public LinkedHashMap(int s) { super(s); accessOrder = false; head = null; } - /** - * Constructs a new {@code LinkedHashMap} instance with the specified - * capacity and load factor. - * - * @param s - * the initial capacity of this map. - * @param lf - * the initial load factor. - * @throws IllegalArgumentException - * when the capacity is less than zero or the load factor is - * less or equal to zero. - */ + /// Constructs a new `LinkedHashMap` instance with the specified + /// capacity and load factor. + /// + /// #### Parameters + /// + /// - `s`: the initial capacity of this map. + /// + /// - `lf`: the initial load factor. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// when the capacity is less than zero or the load factor is + /// less or equal to zero. public LinkedHashMap(int s, float lf) { super(s, lf); accessOrder = false; @@ -99,23 +100,26 @@ public LinkedHashMap(int s, float lf) { tail = null; } - /** - * Constructs a new {@code LinkedHashMap} instance with the specified - * capacity, load factor and a flag specifying the ordering behavior. - * - * @param s - * the initial capacity of this hash map. - * @param lf - * the initial load factor. - * @param order - * {@code true} if the ordering should be done based on the last - * access (from least-recently accessed to most-recently - * accessed), and {@code false} if the ordering should be the - * order in which the entries were inserted. - * @throws IllegalArgumentException - * when the capacity is less than zero or the load factor is - * less or equal to zero. - */ + /// Constructs a new `LinkedHashMap` instance with the specified + /// capacity, load factor and a flag specifying the ordering behavior. + /// + /// #### Parameters + /// + /// - `s`: the initial capacity of this hash map. + /// + /// - `lf`: the initial load factor. + /// + /// - `order`: @param order + /// `true` if the ordering should be done based on the last + /// access (from least-recently accessed to most-recently + /// accessed), and `false` if the ordering should be the + /// order in which the entries were inserted. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// when the capacity is less than zero or the load factor is + /// less or equal to zero. public LinkedHashMap(int s, float lf, boolean order) { super(s, lf); accessOrder = order; @@ -123,13 +127,12 @@ public LinkedHashMap(int s, float lf, boolean order) { tail = null; } - /** - * Constructs a new {@code LinkedHashMap} instance containing the mappings - * from the specified map. The order of the elements is preserved. - * - * @param m - * the mappings to add. - */ + /// Constructs a new `LinkedHashMap` instance containing the mappings + /// from the specified map. The order of the elements is preserved. + /// + /// #### Parameters + /// + /// - `m`: the mappings to add. public LinkedHashMap(Map m) { accessOrder = false; head = null; @@ -283,26 +286,31 @@ public boolean containsValue(Object value) { return false; } - /** - * Create a new element array - * - * @param s - * @return Reference to the element array - */ + /// Create a new element array + /// + /// #### Parameters + /// + /// - `s` + /// + /// #### Returns + /// + /// Reference to the element array @Override @SuppressWarnings("unchecked") HashMap.Entry[] newElementArray(int s) { return new LinkedHashMapEntry[s]; } - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key, or {@code null} - * if no mapping for the specified key is found. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// @return the value of the mapping with the specified key, or `null` + /// if no mapping for the specified key is found. @Override public V get(Object key) { LinkedHashMapEntry m; @@ -353,16 +361,18 @@ HashMap.Entry createHashedEntry(K key, int index, int hash) { return m; } - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no such mapping. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no such mapping. @Override public V put(K key, V value) { V result = putImpl(key, value); @@ -470,25 +480,25 @@ void linkEntry(LinkedHashMapEntry m) { } } - /** - * Returns a set containing all of the mappings in this map. Each mapping is - * an instance of {@link Map.Entry}. As the set is backed by this map, - * changes in one will be reflected in the other. - * - * @return a set of the mappings. - */ + /// Returns a set containing all of the mappings in this map. Each mapping is + /// an instance of `Map.Entry`. As the set is backed by this map, + /// changes in one will be reflected in the other. + /// + /// #### Returns + /// + /// a set of the mappings. @Override public Set> entrySet() { return new LinkedHashMapEntrySet(this); } - /** - * Returns a set of the keys contained in this map. The set is backed by - * this map so changes to one are reflected by the other. The set does not - * support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this map. The set is backed by + /// this map so changes to one are reflected by the other. The set does not + /// support adding. + /// + /// #### Returns + /// + /// a set of the keys. @Override public Set keySet() { if (keySet == null) { @@ -526,25 +536,25 @@ public Iterator iterator() { return keySet; } - /** - * Returns a collection of the values contained in this map. The collection - * is backed by this map so changes to one are reflected by the other. The - * collection supports remove, removeAll, retainAll and clear operations, - * and it does not support add or addAll operations. - *

- * This method returns a collection which is the subclass of - * AbstractCollection. The iterator method of this subclass returns a - * "wrapper object" over the iterator of map's entrySet(). The size method - * wraps the map's size method and the contains method wraps the map's - * containsValue method. - *

- * The collection is created when this method is called for the first time - * and returned in response to all subsequent calls. This method may return - * different collections when multiple concurrent calls occur, since no - * synchronization is performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a collection of the values contained in this map. The collection + /// is backed by this map so changes to one are reflected by the other. The + /// collection supports remove, removeAll, retainAll and clear operations, + /// and it does not support add or addAll operations. + /// + /// This method returns a collection which is the subclass of + /// AbstractCollection. The iterator method of this subclass returns a + /// "wrapper object" over the iterator of map's entrySet(). The size method + /// wraps the map's size method and the contains method wraps the map's + /// containsValue method. + /// + /// The collection is created when this method is called for the first time + /// and returned in response to all subsequent calls. This method may return + /// different collections when multiple concurrent calls occur, since no + /// synchronization is performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. @Override public Collection values() { if (valuesCollection == null) { @@ -573,14 +583,16 @@ public Iterator iterator() { return valuesCollection; } - /** - * Removes the mapping with the specified key from this map. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping or {@code null} if no mapping - * for the specified key was found. - */ + /// Removes the mapping with the specified key from this map. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping or `null` if no mapping + /// for the specified key was found. @Override public V remove(Object key) { LinkedHashMapEntry m = (LinkedHashMapEntry) removeEntry(key); @@ -602,26 +614,29 @@ public V remove(Object key) { return m.value; } - /** - * This method is queried from the put and putAll methods to check if the - * eldest member of the map should be deleted before adding the new member. - * If this map was created with accessOrder = true, then the result of - * removeEldestEntry is assumed to be false. - * - * @param eldest - * the entry to check if it should be removed. - * @return {@code true} if the eldest member should be removed. - */ + /// This method is queried from the put and putAll methods to check if the + /// eldest member of the map should be deleted before adding the new member. + /// If this map was created with accessOrder = true, then the result of + /// removeEldestEntry is assumed to be false. + /// + /// #### Parameters + /// + /// - `eldest`: the entry to check if it should be removed. + /// + /// #### Returns + /// + /// `true` if the eldest member should be removed. protected boolean removeEldestEntry(Map.Entry eldest) { return false; } - /** - * Removes all elements from this map, leaving it empty. - * - * @see #isEmpty() - * @see #size() - */ + /// Removes all elements from this map, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty() + /// + /// - #size() @Override public void clear() { super.clear(); diff --git a/Ports/CLDC11/src/java/util/LinkedHashSet.java b/Ports/CLDC11/src/java/util/LinkedHashSet.java index c6e36453ec..ab2bd020e0 100644 --- a/Ports/CLDC11/src/java/util/LinkedHashSet.java +++ b/Ports/CLDC11/src/java/util/LinkedHashSet.java @@ -17,59 +17,54 @@ package java.util; -/** - * LinkedHashSet is a variant of HashSet. Its entries are kept in a - * doubly-linked list. The iteration order is the order in which entries were - * inserted. - *

- * Null elements are allowed, and all the optional Set operations are supported. - *

- * Like HashSet, LinkedHashSet is not thread safe, so access by multiple threads - * must be synchronized by an external mechanism such as - * {@link Collections#synchronizedSet(Set)}. - * - * @since 1.4 - */ +/// LinkedHashSet is a variant of HashSet. Its entries are kept in a +/// doubly-linked list. The iteration order is the order in which entries were +/// inserted. +/// +/// Null elements are allowed, and all the optional Set operations are supported. +/// +/// Like HashSet, LinkedHashSet is not thread safe, so access by multiple threads +/// must be synchronized by an external mechanism such as +/// `Collections#synchronizedSet(Set)`. +/// +/// #### Since +/// +/// 1.4 public class LinkedHashSet extends HashSet implements Set { - /** - * Constructs a new empty instance of {@code LinkedHashSet}. - */ + /// Constructs a new empty instance of `LinkedHashSet`. public LinkedHashSet() { super(new LinkedHashMap>()); } - /** - * Constructs a new instance of {@code LinkedHashSet} with the specified - * capacity. - * - * @param capacity - * the initial capacity of this {@code LinkedHashSet}. - */ + /// Constructs a new instance of `LinkedHashSet` with the specified + /// capacity. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of this `LinkedHashSet`. public LinkedHashSet(int capacity) { super(new LinkedHashMap>(capacity)); } - /** - * Constructs a new instance of {@code LinkedHashSet} with the specified - * capacity and load factor. - * - * @param capacity - * the initial capacity. - * @param loadFactor - * the initial load factor. - */ + /// Constructs a new instance of `LinkedHashSet` with the specified + /// capacity and load factor. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity. + /// + /// - `loadFactor`: the initial load factor. public LinkedHashSet(int capacity, float loadFactor) { super(new LinkedHashMap>(capacity, loadFactor)); } - /** - * Constructs a new instance of {@code LinkedHashSet} containing the unique - * elements in the specified collection. - * - * @param collection - * the collection of elements to add. - */ + /// Constructs a new instance of `LinkedHashSet` containing the unique + /// elements in the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. public LinkedHashSet(Collection collection) { super(new LinkedHashMap>(collection.size() < 6 ? 11 : collection.size() * 2)); diff --git a/Ports/CLDC11/src/java/util/LinkedList.java b/Ports/CLDC11/src/java/util/LinkedList.java index d1a07b51fa..c45eee4c94 100644 --- a/Ports/CLDC11/src/java/util/LinkedList.java +++ b/Ports/CLDC11/src/java/util/LinkedList.java @@ -17,13 +17,13 @@ package java.util; -/** - * LinkedList is an implementation of List, backed by a linked list. All - * optional operations are supported, adding, removing and replacing. The - * elements can be any objects. - * - * @since 1.2 - */ +/// LinkedList is an implementation of List, backed by a linked list. All +/// optional operations are supported, adding, removing and replacing. The +/// elements can be any objects. +/// +/// #### Since +/// +/// 1.2 public class LinkedList extends AbstractSequentialList implements List, Deque { @@ -225,42 +225,40 @@ public void remove() { } } - /** - * Constructs a new empty instance of {@code LinkedList}. - */ + /// Constructs a new empty instance of `LinkedList`. public LinkedList() { voidLink = new Link(null, null, null); voidLink.previous = voidLink; voidLink.next = voidLink; } - /** - * Constructs a new instance of {@code LinkedList} that holds all of the - * elements contained in the specified {@code collection}. The order of the - * elements in this new {@code LinkedList} will be determined by the - * iteration order of {@code collection}. - * - * @param collection - * the collection of elements to add. - */ + /// Constructs a new instance of `LinkedList` that holds all of the + /// elements contained in the specified `collection`. The order of the + /// elements in this new `LinkedList` will be determined by the + /// iteration order of `collection`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. public LinkedList(Collection collection) { this(); addAll(collection); } - /** - * Inserts the specified object into this {@code LinkedList} at the - * specified location. The object is inserted before any previous element at - * the specified location. If the location is equal to the size of this - * {@code LinkedList}, the object is added at the end. - * - * @param location - * the index at which to insert. - * @param object - * the object to add. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Inserts the specified object into this `LinkedList` at the + /// specified location. The object is inserted before any previous element at + /// the specified location. If the location is equal to the size of this + /// `LinkedList`, the object is added at the end. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `object`: the object to add. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()` @Override public void add(int location, E object) { if (0 <= location && location <= size) { @@ -285,13 +283,15 @@ public void add(int location, E object) { } } - /** - * Adds the specified object at the end of this {@code LinkedList}. - * - * @param object - * the object to add. - * @return always true - */ + /// Adds the specified object at the end of this `LinkedList`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// always true @Override public boolean add(E object) { return addLastImpl(object); @@ -307,24 +307,28 @@ private boolean addLastImpl(E object) { return true; } - /** - * Inserts the objects in the specified collection at the specified location - * in this {@code LinkedList}. The objects are added in the order they are - * returned from the collection's iterator. - * - * @param location - * the index at which to insert. - * @param collection - * the collection of objects - * @return {@code true} if this {@code LinkedList} is modified, - * {@code false} otherwise. - * @throws ClassCastException - * if the class of an object is inappropriate for this list. - * @throws IllegalArgumentException - * if an object cannot be added to this list. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || > size()} - */ + /// Inserts the objects in the specified collection at the specified location + /// in this `LinkedList`. The objects are added in the order they are + /// returned from the collection's iterator. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `collection`: the collection of objects + /// + /// #### Returns + /// + /// @return `true` if this `LinkedList` is modified, + /// `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of an object is inappropriate for this list. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this list. + /// + /// - `IndexOutOfBoundsException`: if `location size()` @Override public boolean addAll(int location, Collection collection) { if (location < 0 || location > size) { @@ -361,14 +365,16 @@ public boolean addAll(int location, Collection collection) { return true; } - /** - * Adds the objects in the specified Collection to this {@code LinkedList}. - * - * @param collection - * the collection of objects. - * @return {@code true} if this {@code LinkedList} is modified, - * {@code false} otherwise. - */ + /// Adds the objects in the specified Collection to this `LinkedList`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if this `LinkedList` is modified, + /// `false` otherwise. @Override public boolean addAll(Collection collection) { int adding = collection.size(); @@ -392,12 +398,11 @@ public boolean addAll(Collection collection) { return true; } - /** - * Adds the specified object at the beginning of this {@code LinkedList}. - * - * @param object - * the object to add. - */ + /// Adds the specified object at the beginning of this `LinkedList`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. public void addFirst(E object) { addFirstImpl(object); } @@ -412,22 +417,22 @@ private boolean addFirstImpl(E object) { return true; } - /** - * Adds the specified object at the end of this {@code LinkedList}. - * - * @param object - * the object to add. - */ + /// Adds the specified object at the end of this `LinkedList`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. public void addLast(E object) { addLastImpl(object); } - /** - * Removes all elements from this {@code LinkedList}, leaving it empty. - * - * @see List#isEmpty - * @see #size - */ + /// Removes all elements from this `LinkedList`, leaving it empty. + /// + /// #### See also + /// + /// - List#isEmpty + /// + /// - #size @Override public void clear() { if (size > 0) { @@ -438,14 +443,16 @@ public void clear() { } } - /** - * Searches this {@code LinkedList} for the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if {@code object} is an element of this - * {@code LinkedList}, {@code false} otherwise - */ + /// Searches this `LinkedList` for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if `object` is an element of this + /// `LinkedList`, `false` otherwise @Override public boolean contains(Object object) { Link link = voidLink.next; @@ -485,13 +492,15 @@ public E get(int location) { throw new IndexOutOfBoundsException(); } - /** - * Returns the first element in this {@code LinkedList}. - * - * @return the first element. - * @throws NoSuchElementException - * if this {@code LinkedList} is empty. - */ + /// Returns the first element in this `LinkedList`. + /// + /// #### Returns + /// + /// the first element. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this `LinkedList` is empty. public E getFirst() { return getFirstImpl(); } @@ -504,13 +513,15 @@ private E getFirstImpl() { throw new NoSuchElementException(); } - /** - * Returns the last element in this {@code LinkedList}. - * - * @return the last element - * @throws NoSuchElementException - * if this {@code LinkedList} is empty - */ + /// Returns the last element in this `LinkedList`. + /// + /// #### Returns + /// + /// the last element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this `LinkedList` is empty public E getLast() { Link last = voidLink.previous; if (last != voidLink) { @@ -543,15 +554,17 @@ public int indexOf(Object object) { return -1; } - /** - * Searches this {@code LinkedList} for the specified object and returns the - * index of the last occurrence. - * - * @param object - * the object to search for - * @return the index of the last occurrence of the object, or -1 if it was - * not found. - */ + /// Searches this `LinkedList` for the specified object and returns the + /// index of the last occurrence. + /// + /// #### Parameters + /// + /// - `object`: the object to search for + /// + /// #### Returns + /// + /// @return the index of the last occurrence of the object, or -1 if it was + /// not found. @Override public int lastIndexOf(Object object) { int pos = size; @@ -576,32 +589,43 @@ public int lastIndexOf(Object object) { return -1; } - /** - * Returns a ListIterator on the elements of this {@code LinkedList}. The - * elements are iterated in the same order that they occur in the - * {@code LinkedList}. The iteration starts at the specified location. - * - * @param location - * the index at which to start the iteration - * @return a ListIterator on the elements of this {@code LinkedList} - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - * @see ListIterator - */ + /// Returns a ListIterator on the elements of this `LinkedList`. The + /// elements are iterated in the same order that they occur in the + /// `LinkedList`. The iteration starts at the specified location. + /// + /// #### Parameters + /// + /// - `location`: the index at which to start the iteration + /// + /// #### Returns + /// + /// a ListIterator on the elements of this `LinkedList` + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()` + /// + /// #### See also + /// + /// - ListIterator @Override public ListIterator listIterator(int location) { return new LinkIterator(this, location); } - /** - * Removes the object at the specified location from this {@code LinkedList}. - * - * @param location - * the index of the object to remove - * @return the removed object - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Removes the object at the specified location from this `LinkedList`. + /// + /// #### Parameters + /// + /// - `location`: the index of the object to remove + /// + /// #### Returns + /// + /// the removed object + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()` @Override public E remove(int location) { if (0 <= location && location < size) { @@ -631,13 +655,15 @@ public boolean remove(Object object) { return removeFirstOccurrenceImpl(object); } - /** - * Removes the first object from this {@code LinkedList}. - * - * @return the removed object. - * @throws NoSuchElementException - * if this {@code LinkedList} is empty. - */ + /// Removes the first object from this `LinkedList`. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this `LinkedList` is empty. public E removeFirst() { return removeFirstImpl(); } @@ -655,13 +681,15 @@ private E removeFirstImpl() { throw new NoSuchElementException(); } - /** - * Removes the last object from this {@code LinkedList}. - * - * @return the removed object. - * @throws NoSuchElementException - * if this {@code LinkedList} is empty. - */ + /// Removes the last object from this `LinkedList`. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this `LinkedList` is empty. public E removeLast() { return removeLastImpl(); } @@ -679,113 +707,146 @@ private E removeLastImpl() { throw new NoSuchElementException(); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#descendingIterator() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#descendingIterator() public Iterator descendingIterator() { return new ReverseLinkIterator(this); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#offerFirst(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#offerFirst(java.lang.Object) public boolean offerFirst(E e) { return addFirstImpl(e); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#offerLast(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#offerLast(java.lang.Object) public boolean offerLast(E e) { return addLastImpl(e); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#peekFirst() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#peekFirst() public E peekFirst() { return peekFirstImpl(); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#peekLast() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#peekLast() public E peekLast() { Link last = voidLink.previous; return (last == voidLink) ? null : last.data; } - /** - * {@inheritDoc} - * - * @see java.util.Deque#pollFirst() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#pollFirst() public E pollFirst() { return (size == 0) ? null : removeFirstImpl(); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#pollLast() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#pollLast() public E pollLast() { return (size == 0) ? null : removeLastImpl(); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#pop() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#pop() public E pop() { return removeFirstImpl(); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#push(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#push(java.lang.Object) public void push(E e) { addFirstImpl(e); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#removeFirstOccurrence(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#removeFirstOccurrence(java.lang.Object) public boolean removeFirstOccurrence(Object o) { return removeFirstOccurrenceImpl(o); } - /** - * {@inheritDoc} - * - * @see java.util.Deque#removeLastOccurrence(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.Deque#removeLastOccurrence(java.lang.Object) public boolean removeLastOccurrence(Object o) { Iterator iter = new ReverseLinkIterator(this); return removeOneOccurrence(o, iter); @@ -807,22 +868,26 @@ private boolean removeOneOccurrence(Object o, Iterator iter) { return false; } - /** - * Replaces the element at the specified location in this {@code LinkedList} - * with the specified object. - * - * @param location - * the index at which to put the specified object. - * @param object - * the object to add. - * @return the previous element at the index. - * @throws ClassCastException - * if the class of an object is inappropriate for this list. - * @throws IllegalArgumentException - * if an object cannot be added to this list. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Replaces the element at the specified location in this `LinkedList` + /// with the specified object. + /// + /// #### Parameters + /// + /// - `location`: the index at which to put the specified object. + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// the previous element at the index. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the class of an object is inappropriate for this list. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this list. + /// + /// - `IndexOutOfBoundsException`: if `location = size()` @Override public E set(int location, E object) { if (0 <= location && location < size) { @@ -843,11 +908,11 @@ public E set(int location, E object) { throw new IndexOutOfBoundsException(); } - /** - * Returns the number of elements in this {@code LinkedList}. - * - * @return the number of elements in this {@code LinkedList}. - */ + /// Returns the number of elements in this `LinkedList`. + /// + /// #### Returns + /// + /// the number of elements in this `LinkedList`. @Override public int size() { return size; @@ -878,12 +943,12 @@ public E element() { return getFirstImpl(); } - /** - * Returns a new array containing all elements contained in this - * {@code LinkedList}. - * - * @return an array of the elements from this {@code LinkedList}. - */ + /// Returns a new array containing all elements contained in this + /// `LinkedList`. + /// + /// #### Returns + /// + /// an array of the elements from this `LinkedList`. @Override public Object[] toArray() { int index = 0; @@ -896,21 +961,26 @@ public Object[] toArray() { return contents; } - /** - * Returns an array containing all elements contained in this - * {@code LinkedList}. If the specified array is large enough to hold the - * elements, the specified array is used, otherwise an array of the same - * type is created. If the specified array is used and is larger than this - * {@code LinkedList}, the array element following the collection elements - * is set to null. - * - * @param contents - * the array. - * @return an array of the elements from this {@code LinkedList}. - * @throws ArrayStoreException - * if the type of an element in this {@code LinkedList} cannot - * be stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this + /// `LinkedList`. If the specified array is large enough to hold the + /// elements, the specified array is used, otherwise an array of the same + /// type is created. If the specified array is used and is larger than this + /// `LinkedList`, the array element following the collection elements + /// is set to null. + /// + /// #### Parameters + /// + /// - `contents`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `LinkedList`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// if the type of an element in this `LinkedList` cannot + /// be stored in the type of the specified array. @Override @SuppressWarnings("unchecked") public T[] toArray(T[] contents) { diff --git a/Ports/CLDC11/src/java/util/List.java b/Ports/CLDC11/src/java/util/List.java index 68e1ad9b67..0fc8fa7a29 100644 --- a/Ports/CLDC11/src/java/util/List.java +++ b/Ports/CLDC11/src/java/util/List.java @@ -18,336 +18,417 @@ package java.util; -/** - * A {@code List} is a collection which maintains an ordering for its elements. Every - * element in the {@code List} has an index. Each element can thus be accessed by its - * index, with the first index being zero. Normally, {@code List}s allow duplicate - * elements, as compared to Sets, where elements have to be unique. - */ +/// A `List` is a collection which maintains an ordering for its elements. Every +/// element in the `List` has an index. Each element can thus be accessed by its +/// index, with the first index being zero. Normally, `List`s allow duplicate +/// elements, as compared to Sets, where elements have to be unique. public interface List extends Collection { - /** - * Inserts the specified object into this {@code List} at the specified location. - * The object is inserted before the current element at the specified - * location. If the location is equal to the size of this {@code List}, the object - * is added at the end. If the location is smaller than the size of this - * {@code List}, then all elements beyond the specified location are moved by one - * position towards the end of the {@code List}. - * - * @param location - * the index at which to insert. - * @param object - * the object to add. - * @throws UnsupportedOperationException - * if adding to this {@code List} is not supported. - * @throws ClassCastException - * if the class of the object is inappropriate for this - * {@code List}. - * @throws IllegalArgumentException - * if the object cannot be added to this {@code List}. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || location > size()} - */ + /// Inserts the specified object into this `List` at the specified location. + /// The object is inserted before the current element at the specified + /// location. If the location is equal to the size of this `List`, the object + /// is added at the end. If the location is smaller than the size of this + /// `List`, then all elements beyond the specified location are moved by one + /// position towards the end of the `List`. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `object`: the object to add. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `List` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the object is inappropriate for this + /// `List`. + /// + /// - `IllegalArgumentException`: if the object cannot be added to this `List`. + /// + /// - `IndexOutOfBoundsException`: if `location size()` public void add(int location, E object); - /** - * Adds the specified object at the end of this {@code List}. - * - * @param object - * the object to add. - * @return always true. - * @throws UnsupportedOperationException - * if adding to this {@code List} is not supported. - * @throws ClassCastException - * if the class of the object is inappropriate for this - * {@code List}. - * @throws IllegalArgumentException - * if the object cannot be added to this {@code List}. - */ + /// Adds the specified object at the end of this `List`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// always true. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `List` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the object is inappropriate for this + /// `List`. + /// + /// - `IllegalArgumentException`: if the object cannot be added to this `List`. public boolean add(E object); - /** - * Inserts the objects in the specified collection at the specified location - * in this {@code List}. The objects are added in the order they are returned from - * the collection's iterator. - * - * @param location - * the index at which to insert. - * @param collection - * the collection of objects to be inserted. - * @return true if this {@code List} has been modified through the insertion, false - * otherwise (i.e. if the passed collection was empty). - * @throws UnsupportedOperationException - * if adding to this {@code List} is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this - * {@code List}. - * @throws IllegalArgumentException - * if an object cannot be added to this {@code List}. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || > size()} - */ + /// Inserts the objects in the specified collection at the specified location + /// in this `List`. The objects are added in the order they are returned from + /// the collection's iterator. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert. + /// + /// - `collection`: the collection of objects to be inserted. + /// + /// #### Returns + /// + /// @return true if this `List` has been modified through the insertion, false + /// otherwise (i.e. if the passed collection was empty). + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `List` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of an object is inappropriate for this + /// `List`. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this `List`. + /// + /// - `IndexOutOfBoundsException`: if `location size()` public boolean addAll(int location, Collection collection); - /** - * Adds the objects in the specified collection to the end of this {@code List}. The - * objects are added in the order in which they are returned from the - * collection's iterator. - * - * @param collection - * the collection of objects. - * @return {@code true} if this {@code List} is modified, {@code false} otherwise - * (i.e. if the passed collection was empty). - * @throws UnsupportedOperationException - * if adding to this {@code List} is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this - * {@code List}. - * @throws IllegalArgumentException - * if an object cannot be added to this {@code List}. - */ + /// Adds the objects in the specified collection to the end of this `List`. The + /// objects are added in the order in which they are returned from the + /// collection's iterator. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if this `List` is modified, `false` otherwise + /// (i.e. if the passed collection was empty). + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `List` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of an object is inappropriate for this + /// `List`. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this `List`. public boolean addAll(Collection collection); - /** - * Removes all elements from this {@code List}, leaving it empty. - * - * @throws UnsupportedOperationException - * if removing from this {@code List} is not supported. - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `List`, leaving it empty. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `List` is not supported. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size public void clear(); - /** - * Tests whether this {@code List} contains the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if object is an element of this {@code List}, {@code false} - * otherwise - */ + /// Tests whether this `List` contains the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if object is an element of this `List`, `false` + /// otherwise public boolean contains(Object object); - /** - * Tests whether this {@code List} contains all objects contained in the - * specified collection. - * - * @param collection - * the collection of objects - * @return {@code true} if all objects in the specified collection are - * elements of this {@code List}, {@code false} otherwise. - */ + /// Tests whether this `List` contains all objects contained in the + /// specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects + /// + /// #### Returns + /// + /// @return `true` if all objects in the specified collection are + /// elements of this `List`, `false` otherwise. public boolean containsAll(Collection collection); - /** - * Compares the given object with the {@code List}, and returns true if they - * represent the same object using a class specific comparison. For - * {@code List}s, this means that they contain the same elements in exactly the same - * order. - * - * @param object - * the object to compare with this object. - * @return boolean {@code true} if the object is the same as this object, - * and {@code false} if it is different from this object. - * @see #hashCode - */ + /// Compares the given object with the `List`, and returns true if they + /// represent the *same* object using a class specific comparison. For + /// `List`s, this means that they contain the same elements in exactly the same + /// order. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object. + /// + /// #### Returns + /// + /// @return boolean `true` if the object is the same as this object, + /// and `false` if it is different from this object. + /// + /// #### See also + /// + /// - #hashCode public boolean equals(Object object); - /** - * Returns the element at the specified location in this {@code List}. - * - * @param location - * the index of the element to return. - * @return the element at the specified location. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Returns the element at the specified location in this `List`. + /// + /// #### Parameters + /// + /// - `location`: the index of the element to return. + /// + /// #### Returns + /// + /// the element at the specified location. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public E get(int location); - /** - * Returns the hash code for this {@code List}. It is calculated by taking each - * element' hashcode and its position in the {@code List} into account. - * - * @return the hash code of the {@code List}. - */ + /// Returns the hash code for this `List`. It is calculated by taking each + /// element' hashcode and its position in the `List` into account. + /// + /// #### Returns + /// + /// the hash code of the `List`. public int hashCode(); - /** - * Searches this {@code List} for the specified object and returns the index of the - * first occurrence. - * - * @param object - * the object to search for. - * @return the index of the first occurrence of the object or -1 if the - * object was not found. - */ + /// Searches this `List` for the specified object and returns the index of the + /// first occurrence. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return the index of the first occurrence of the object or -1 if the + /// object was not found. public int indexOf(Object object); - /** - * Returns whether this {@code List} contains no elements. - * - * @return {@code true} if this {@code List} has no elements, {@code false} - * otherwise. - * @see #size - */ + /// Returns whether this `List` contains no elements. + /// + /// #### Returns + /// + /// @return `true` if this `List` has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size public boolean isEmpty(); - /** - * Returns an iterator on the elements of this {@code List}. The elements are - * iterated in the same order as they occur in the {@code List}. - * - * @return an iterator on the elements of this {@code List}. - * @see Iterator - */ + /// Returns an iterator on the elements of this `List`. The elements are + /// iterated in the same order as they occur in the `List`. + /// + /// #### Returns + /// + /// an iterator on the elements of this `List`. + /// + /// #### See also + /// + /// - Iterator public Iterator iterator(); - /** - * Searches this {@code List} for the specified object and returns the index of the - * last occurrence. - * - * @param object - * the object to search for. - * @return the index of the last occurrence of the object, or -1 if the - * object was not found. - */ + /// Searches this `List` for the specified object and returns the index of the + /// last occurrence. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return the index of the last occurrence of the object, or -1 if the + /// object was not found. public int lastIndexOf(Object object); - /** - * Returns a {@code List} iterator on the elements of this {@code List}. The elements are - * iterated in the same order that they occur in the {@code List}. - * - * @return a {@code List} iterator on the elements of this {@code List} - * - * @see ListIterator - */ + /// Returns a `List` iterator on the elements of this `List`. The elements are + /// iterated in the same order that they occur in the `List`. + /// + /// #### Returns + /// + /// a `List` iterator on the elements of this `List` + /// + /// #### See also + /// + /// - ListIterator public ListIterator listIterator(); - /** - * Returns a list iterator on the elements of this {@code List}. The elements are - * iterated in the same order as they occur in the {@code List}. The iteration - * starts at the specified location. - * - * @param location - * the index at which to start the iteration. - * @return a list iterator on the elements of this {@code List}. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || location > size()} - * @see ListIterator - */ + /// Returns a list iterator on the elements of this `List`. The elements are + /// iterated in the same order as they occur in the `List`. The iteration + /// starts at the specified location. + /// + /// #### Parameters + /// + /// - `location`: the index at which to start the iteration. + /// + /// #### Returns + /// + /// a list iterator on the elements of this `List`. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location size()` + /// + /// #### See also + /// + /// - ListIterator public ListIterator listIterator(int location); - /** - * Removes the object at the specified location from this {@code List}. - * - * @param location - * the index of the object to remove. - * @return the removed object. - * @throws UnsupportedOperationException - * if removing from this {@code List} is not supported. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Removes the object at the specified location from this `List`. + /// + /// #### Parameters + /// + /// - `location`: the index of the object to remove. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `List` is not supported. + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public E remove(int location); - /** - * Removes the first occurrence of the specified object from this {@code List}. - * - * @param object - * the object to remove. - * @return true if this {@code List} was modified by this operation, false - * otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code List} is not supported. - */ + /// Removes the first occurrence of the specified object from this `List`. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// @return true if this `List` was modified by this operation, false + /// otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `List` is not supported. public boolean remove(Object object); - /** - * Removes all occurrences in this {@code List} of each object in the specified - * collection. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this {@code List} is modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code List} is not supported. - */ + /// Removes all occurrences in this `List` of each object in the specified + /// collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// `true` if this `List` is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `List` is not supported. public boolean removeAll(Collection collection); - /** - * Removes all objects from this {@code List} that are not contained in the - * specified collection. - * - * @param collection - * the collection of objects to retain. - * @return {@code true} if this {@code List} is modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * if removing from this {@code List} is not supported. - */ + /// Removes all objects from this `List` that are not contained in the + /// specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to retain. + /// + /// #### Returns + /// + /// `true` if this `List` is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `List` is not supported. public boolean retainAll(Collection collection); - /** - * Replaces the element at the specified location in this {@code List} with the - * specified object. This operation does not change the size of the {@code List}. - * - * @param location - * the index at which to put the specified object. - * @param object - * the object to insert. - * @return the previous element at the index. - * @throws UnsupportedOperationException - * if replacing elements in this {@code List} is not supported. - * @throws ClassCastException - * if the class of an object is inappropriate for this - * {@code List}. - * @throws IllegalArgumentException - * if an object cannot be added to this {@code List}. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || >= size()} - */ + /// Replaces the element at the specified location in this `List` with the + /// specified object. This operation does not change the size of the `List`. + /// + /// #### Parameters + /// + /// - `location`: the index at which to put the specified object. + /// + /// - `object`: the object to insert. + /// + /// #### Returns + /// + /// the previous element at the index. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if replacing elements in this `List` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of an object is inappropriate for this + /// `List`. + /// + /// - `IllegalArgumentException`: if an object cannot be added to this `List`. + /// + /// - `IndexOutOfBoundsException`: if `location = size()` public E set(int location, E object); - /** - * Returns the number of elements in this {@code List}. - * - * @return the number of elements in this {@code List}. - */ + /// Returns the number of elements in this `List`. + /// + /// #### Returns + /// + /// the number of elements in this `List`. public int size(); - /** - * Returns a {@code List} of the specified portion of this {@code List} from the given start - * index to the end index minus one. The returned {@code List} is backed by this - * {@code List} so changes to it are reflected by the other. - * - * @param start - * the index at which to start the sublist. - * @param end - * the index one past the end of the sublist. - * @return a list of a portion of this {@code List}. - * @throws IndexOutOfBoundsException - * if {@code start < 0, start > end} or {@code end > - * size()} - */ + /// Returns a `List` of the specified portion of this `List` from the given start + /// index to the end index minus one. The returned `List` is backed by this + /// `List` so changes to it are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the index at which to start the sublist. + /// + /// - `end`: the index one past the end of the sublist. + /// + /// #### Returns + /// + /// a list of a portion of this `List`. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `start end` or `end > + /// size()` public List subList(int start, int end); - /** - * Returns an array containing all elements contained in this {@code List}. - * - * @return an array of the elements from this {@code List}. - */ + /// Returns an array containing all elements contained in this `List`. + /// + /// #### Returns + /// + /// an array of the elements from this `List`. public Object[] toArray(); - /** - * Returns an array containing all elements contained in this {@code List}. If the - * specified array is large enough to hold the elements, the specified array - * is used, otherwise an array of the same type is created. If the specified - * array is used and is larger than this {@code List}, the array element following - * the collection elements is set to null. - * - * @param array - * the array. - * @return an array of the elements from this {@code List}. - * @throws ArrayStoreException - * if the type of an element in this {@code List} cannot be stored - * in the type of the specified array. - */ + /// Returns an array containing all elements contained in this `List`. If the + /// specified array is large enough to hold the elements, the specified array + /// is used, otherwise an array of the same type is created. If the specified + /// array is used and is larger than this `List`, the array element following + /// the collection elements is set to null. + /// + /// #### Parameters + /// + /// - `array`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this `List`. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// if the type of an element in this `List` cannot be stored + /// in the type of the specified array. public T[] toArray(T[] array); } diff --git a/Ports/CLDC11/src/java/util/ListIterator.java b/Ports/CLDC11/src/java/util/ListIterator.java index 1c62a22898..cce73d4c3d 100644 --- a/Ports/CLDC11/src/java/util/ListIterator.java +++ b/Ports/CLDC11/src/java/util/ListIterator.java @@ -18,115 +18,142 @@ package java.util; -/** - * An ListIterator is used to sequence over a List of objects. ListIterator can - * move backwards or forwards through the list. - */ +/// An ListIterator is used to sequence over a List of objects. ListIterator can +/// move backwards or forwards through the list. public interface ListIterator extends Iterator { - /** - * Inserts the specified object into the list between {@code next} and - * {@code previous}. The object inserted will be the previous object. - * - * @param object - * the object to insert. - * @throws UnsupportedOperationException - * if adding is not supported by the list being iterated. - * @throws ClassCastException - * if the class of the object is inappropriate for the list. - * @throws IllegalArgumentException - * if the object cannot be added to the list. - */ + /// Inserts the specified object into the list between `next` and + /// `previous`. The object inserted will be the previous object. + /// + /// #### Parameters + /// + /// - `object`: the object to insert. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding is not supported by the list being iterated. + /// + /// - `ClassCastException`: if the class of the object is inappropriate for the list. + /// + /// - `IllegalArgumentException`: if the object cannot be added to the list. void add(E object); - /** - * Returns whether there are more elements to iterate. - * - * @return {@code true} if there are more elements, {@code false} otherwise. - * @see #next - */ + /// Returns whether there are more elements to iterate. + /// + /// #### Returns + /// + /// `true` if there are more elements, `false` otherwise. + /// + /// #### See also + /// + /// - #next public boolean hasNext(); - /** - * Returns whether there are previous elements to iterate. - * - * @return {@code true} if there are previous elements, {@code false} - * otherwise. - * @see #previous - */ + /// Returns whether there are previous elements to iterate. + /// + /// #### Returns + /// + /// @return `true` if there are previous elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #previous public boolean hasPrevious(); - /** - * Returns the next object in the iteration. - * - * @return the next object. - * @throws NoSuchElementException - * if there are no more elements. - * @see #hasNext - */ + /// Returns the next object in the iteration. + /// + /// #### Returns + /// + /// the next object. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there are no more elements. + /// + /// #### See also + /// + /// - #hasNext public E next(); - /** - * Returns the index of the next object in the iteration. - * - * @return the index of the next object, or the size of the list if the - * iterator is at the end. - * @throws NoSuchElementException - * if there are no more elements. - * @see #next - */ + /// Returns the index of the next object in the iteration. + /// + /// #### Returns + /// + /// @return the index of the next object, or the size of the list if the + /// iterator is at the end. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there are no more elements. + /// + /// #### See also + /// + /// - #next public int nextIndex(); - /** - * Returns the previous object in the iteration. - * - * @return the previous object. - * @throws NoSuchElementException - * if there are no previous elements. - * @see #hasPrevious - */ + /// Returns the previous object in the iteration. + /// + /// #### Returns + /// + /// the previous object. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there are no previous elements. + /// + /// #### See also + /// + /// - #hasPrevious public E previous(); - /** - * Returns the index of the previous object in the iteration. - * - * @return the index of the previous object, or -1 if the iterator is at the - * beginning. - * @throws NoSuchElementException - * if there are no previous elements. - * @see #previous - */ + /// Returns the index of the previous object in the iteration. + /// + /// #### Returns + /// + /// @return the index of the previous object, or -1 if the iterator is at the + /// beginning. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there are no previous elements. + /// + /// #### See also + /// + /// - #previous public int previousIndex(); - /** - * Removes the last object returned by {@code next} or {@code previous} from - * the list. - * - * @throws UnsupportedOperationException - * if removing is not supported by the list being iterated. - * @throws IllegalStateException - * if {@code next} or {@code previous} have not been called, or - * {@code remove} or {@code add} have already been called after - * the last call to {@code next} or {@code previous}. - */ + /// Removes the last object returned by `next` or `previous` from + /// the list. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing is not supported by the list being iterated. + /// + /// - `IllegalStateException`: @throws IllegalStateException + /// if `next` or `previous` have not been called, or + /// `remove` or `add` have already been called after + /// the last call to `next` or `previous`. public void remove(); - /** - * Replaces the last object returned by {@code next} or {@code previous} - * with the specified object. - * - * @param object - * the object to set. - * @throws UnsupportedOperationException - * if setting is not supported by the list being iterated - * @throws ClassCastException - * if the class of the object is inappropriate for the list. - * @throws IllegalArgumentException - * if the object cannot be added to the list. - * @throws IllegalStateException - * if {@code next} or {@code previous} have not been called, or - * {@code remove} or {@code add} have already been called after - * the last call to {@code next} or {@code previous}. - */ + /// Replaces the last object returned by `next` or `previous` + /// with the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to set. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if setting is not supported by the list being iterated + /// + /// - `ClassCastException`: if the class of the object is inappropriate for the list. + /// + /// - `IllegalArgumentException`: if the object cannot be added to the list. + /// + /// - `IllegalStateException`: @throws IllegalStateException + /// if `next` or `previous` have not been called, or + /// `remove` or `add` have already been called after + /// the last call to `next` or `previous`. void set(E object); } diff --git a/Ports/CLDC11/src/java/util/Locale.java b/Ports/CLDC11/src/java/util/Locale.java index 6326bd0aa4..dd07048be1 100644 --- a/Ports/CLDC11/src/java/util/Locale.java +++ b/Ports/CLDC11/src/java/util/Locale.java @@ -1,9 +1,6 @@ package java.util; -/** - * - * @author Shai Almog - */ +/// @author Shai Almog public class Locale { private static Locale defaultLocale; private String language; diff --git a/Ports/CLDC11/src/java/util/Map.java b/Ports/CLDC11/src/java/util/Map.java index 7509d1acf4..68bd3283bb 100644 --- a/Ports/CLDC11/src/java/util/Map.java +++ b/Ports/CLDC11/src/java/util/Map.java @@ -18,236 +18,276 @@ package java.util; -/** - * A {@code Map} is a data structure consisting of a set of keys and values - * in which each key is mapped to a single value. The class of the objects - * used as keys is declared when the {@code Map} is declared, as is the - * class of the corresponding values. - *

- * A {@code Map} provides helper methods to iterate through all of the - * keys contained in it, as well as various methods to access and update - * the key/value pairs. - */ +/// A `Map` is a data structure consisting of a set of keys and values +/// in which each key is mapped to a single value. The class of the objects +/// used as keys is declared when the `Map` is declared, as is the +/// class of the corresponding values. +/// +/// A `Map` provides helper methods to iterate through all of the +/// keys contained in it, as well as various methods to access and update +/// the key/value pairs. public interface Map { - /** - * {@code Map.Entry} is a key/value mapping contained in a {@code Map}. - */ + /// `Map.Entry` is a key/value mapping contained in a `Map`. public static interface Entry { - /** - * Compares the specified object to this {@code Map.Entry} and returns if they - * are equal. To be equal, the object must be an instance of {@code Map.Entry} and have the - * same key and value. - * - * @param object - * the {@code Object} to compare with this {@code Object}. - * @return {@code true} if the specified {@code Object} is equal to this - * {@code Map.Entry}, {@code false} otherwise. - * @see #hashCode() - */ + /// Compares the specified object to this `Map.Entry` and returns if they + /// are equal. To be equal, the object must be an instance of `Map.Entry` and have the + /// same key and value. + /// + /// #### Parameters + /// + /// - `object`: the `Object` to compare with this `Object`. + /// + /// #### Returns + /// + /// @return `true` if the specified `Object` is equal to this + /// `Map.Entry`, `false` otherwise. + /// + /// #### See also + /// + /// - #hashCode() public boolean equals(Object object); - /** - * Returns the key. - * - * @return the key - */ + /// Returns the key. + /// + /// #### Returns + /// + /// the key public K getKey(); - /** - * Returns the value. - * - * @return the value - */ + /// Returns the value. + /// + /// #### Returns + /// + /// the value public V getValue(); - /** - * Returns an integer hash code for the receiver. {@code Object} which are - * equal return the same value for this method. - * - * @return the receiver's hash code. - * @see #equals(Object) - */ + /// Returns an integer hash code for the receiver. `Object` which are + /// equal return the same value for this method. + /// + /// #### Returns + /// + /// the receiver's hash code. + /// + /// #### See also + /// + /// - #equals(Object) public int hashCode(); - /** - * Sets the value of this entry to the specified value, replacing any - * existing value. - * - * @param object - * the new value to set. - * @return object the replaced value of this entry. - */ + /// Sets the value of this entry to the specified value, replacing any + /// existing value. + /// + /// #### Parameters + /// + /// - `object`: the new value to set. + /// + /// #### Returns + /// + /// object the replaced value of this entry. public V setValue(V object); }; - /** - * Removes all elements from this {@code Map}, leaving it empty. - * - * @throws UnsupportedOperationException - * if removing elements from this {@code Map} is not supported. - * @see #isEmpty() - * @see #size() - */ + /// Removes all elements from this `Map`, leaving it empty. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing elements from this `Map` is not supported. + /// + /// #### See also + /// + /// - #isEmpty() + /// + /// - #size() public void clear(); - /** - * Returns whether this {@code Map} contains the specified key. - * - * @param key - * the key to search for. - * @return {@code true} if this map contains the specified key, - * {@code false} otherwise. - */ + /// Returns whether this `Map` contains the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified key, + /// `false` otherwise. public boolean containsKey(Object key); - /** - * Returns whether this {@code Map} contains the specified value. - * - * @param value - * the value to search for. - * @return {@code true} if this map contains the specified value, - * {@code false} otherwise. - */ + /// Returns whether this `Map` contains the specified value. + /// + /// #### Parameters + /// + /// - `value`: the value to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified value, + /// `false` otherwise. public boolean containsValue(Object value); - /** - * Returns a {@code Set} containing all of the mappings in this {@code Map}. Each mapping is - * an instance of {@link Map.Entry}. As the {@code Set} is backed by this {@code Map}, - * changes in one will be reflected in the other. - * - * @return a set of the mappings - */ + /// Returns a `Set` containing all of the mappings in this `Map`. Each mapping is + /// an instance of `Map.Entry`. As the `Set` is backed by this `Map`, + /// changes in one will be reflected in the other. + /// + /// #### Returns + /// + /// a set of the mappings public Set> entrySet(); - /** - * Compares the argument to the receiver, and returns {@code true} if the - * specified object is a {@code Map} and both {@code Map}s contain the same mappings. - * - * @param object - * the {@code Object} to compare with this {@code Object}. - * @return boolean {@code true} if the {@code Object} is the same as this {@code Object} - * {@code false} if it is different from this {@code Object}. - * @see #hashCode() - * @see #entrySet() - */ + /// Compares the argument to the receiver, and returns `true` if the + /// specified object is a `Map` and both `Map`s contain the same mappings. + /// + /// #### Parameters + /// + /// - `object`: the `Object` to compare with this `Object`. + /// + /// #### Returns + /// + /// @return boolean `true` if the `Object` is the same as this `Object` + /// `false` if it is different from this `Object`. + /// + /// #### See also + /// + /// - #hashCode() + /// + /// - #entrySet() public boolean equals(Object object); - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key, or {@code null} - * if no mapping for the specified key is found. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// @return the value of the mapping with the specified key, or `null` + /// if no mapping for the specified key is found. public V get(Object key); - /** - * Returns an integer hash code for the receiver. {@code Object}s which are equal - * return the same value for this method. - * - * @return the receiver's hash. - * @see #equals(Object) - */ + /// Returns an integer hash code for the receiver. `Object`s which are equal + /// return the same value for this method. + /// + /// #### Returns + /// + /// the receiver's hash. + /// + /// #### See also + /// + /// - #equals(Object) public int hashCode(); - /** - * Returns whether this map is empty. - * - * @return {@code true} if this map has no elements, {@code false} - * otherwise. - * @see #size() - */ + /// Returns whether this map is empty. + /// + /// #### Returns + /// + /// @return `true` if this map has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size() public boolean isEmpty(); - /** - * Returns a set of the keys contained in this {@code Map}. The {@code Set} is backed by - * this {@code Map} so changes to one are reflected by the other. The {@code Set} does not - * support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this `Map`. The `Set` is backed by + /// this `Map` so changes to one are reflected by the other. The `Set` does not + /// support adding. + /// + /// #### Returns + /// + /// a set of the keys. public Set keySet(); - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no mapping. - * @throws UnsupportedOperationException - * if adding to this {@code Map} is not supported. - * @throws ClassCastException - * if the class of the key or value is inappropriate for - * this {@code Map}. - * @throws IllegalArgumentException - * if the key or value cannot be added to this {@code Map}. - * @throws NullPointerException - * if the key or value is {@code null} and this {@code Map} does - * not support {@code null} keys or values. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no mapping. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `Map` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the key or value is inappropriate for + /// this `Map`. + /// + /// - `IllegalArgumentException`: if the key or value cannot be added to this `Map`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the key or value is `null` and this `Map` does + /// not support `null` keys or values. public V put(K key, V value); - /** - * Copies every mapping in the specified {@code Map} to this {@code Map}. - * - * @param map - * the {@code Map} to copy mappings from. - * @throws UnsupportedOperationException - * if adding to this {@code Map} is not supported. - * @throws ClassCastException - * if the class of a key or a value of the specified {@code Map} is - * inappropriate for this {@code Map}. - * @throws IllegalArgumentException - * if a key or value cannot be added to this {@code Map}. - * @throws NullPointerException - * if a key or value is {@code null} and this {@code Map} does not - * support {@code null} keys or values. - */ + /// Copies every mapping in the specified `Map` to this `Map`. + /// + /// #### Parameters + /// + /// - `map`: the `Map` to copy mappings from. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if adding to this `Map` is not supported. + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of a key or a value of the specified `Map` is + /// inappropriate for this `Map`. + /// + /// - `IllegalArgumentException`: if a key or value cannot be added to this `Map`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if a key or value is `null` and this `Map` does not + /// support `null` keys or values. public void putAll(Map map); - /** - * Removes a mapping with the specified key from this {@code Map}. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping or {@code null} if no mapping - * for the specified key was found. - * @throws UnsupportedOperationException - * if removing from this {@code Map} is not supported. - */ + /// Removes a mapping with the specified key from this `Map`. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping or `null` if no mapping + /// for the specified key was found. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: if removing from this `Map` is not supported. public V remove(Object key); - /** - * Returns the number of mappings in this {@code Map}. - * - * @return the number of mappings in this {@code Map}. - */ + /// Returns the number of mappings in this `Map`. + /// + /// #### Returns + /// + /// the number of mappings in this `Map`. public int size(); - /** - * Returns a {@code Collection} of the values contained in this {@code Map}. The {@code Collection} - * is backed by this {@code Map} so changes to one are reflected by the other. The - * {@code Collection} supports {@link Collection#remove}, {@link Collection#removeAll}, - * {@link Collection#retainAll}, and {@link Collection#clear} operations, - * and it does not support {@link Collection#add} or {@link Collection#addAll} operations. - *

- * This method returns a {@code Collection} which is the subclass of - * {@link AbstractCollection}. The {@link AbstractCollection#iterator} method of this subclass returns a - * "wrapper object" over the iterator of this {@code Map}'s {@link #entrySet()}. The {@link AbstractCollection#size} method - * wraps this {@code Map}'s {@link #size} method and the {@link AbstractCollection#contains} method wraps this {@code Map}'s - * {@link #containsValue} method. - *

- * The collection is created when this method is called at first time and - * returned in response to all subsequent calls. This method may return - * different Collection when multiple calls to this method, since it has no - * synchronization performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a `Collection` of the values contained in this `Map`. The `Collection` + /// is backed by this `Map` so changes to one are reflected by the other. The + /// `Collection` supports `Collection#remove`, `Collection#removeAll`, + /// `Collection#retainAll`, and `Collection#clear` operations, + /// and it does not support `Collection#add` or `Collection#addAll` operations. + /// + /// This method returns a `Collection` which is the subclass of + /// `AbstractCollection`. The `AbstractCollection#iterator` method of this subclass returns a + /// "wrapper object" over the iterator of this `Map`'s `#entrySet()`. The `AbstractCollection#size` method + /// wraps this `Map`'s `#size` method and the `AbstractCollection#contains` method wraps this `Map`'s + /// `#containsValue` method. + /// + /// The collection is created when this method is called at first time and + /// returned in response to all subsequent calls. This method may return + /// different Collection when multiple calls to this method, since it has no + /// synchronization performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. public Collection values(); } diff --git a/Ports/CLDC11/src/java/util/MapEntry.java b/Ports/CLDC11/src/java/util/MapEntry.java index 6768e0d5fa..e898ede696 100644 --- a/Ports/CLDC11/src/java/util/MapEntry.java +++ b/Ports/CLDC11/src/java/util/MapEntry.java @@ -17,9 +17,7 @@ package java.util; -/** - * MapEntry is an internal class which provides an implementation of Map.Entry. - */ +/// MapEntry is an internal class which provides an implementation of Map.Entry. class MapEntry implements Map.Entry { K key; diff --git a/Ports/CLDC11/src/java/util/NavigableMap.java b/Ports/CLDC11/src/java/util/NavigableMap.java index 75c73bb6ae..1ba63793cd 100644 --- a/Ports/CLDC11/src/java/util/NavigableMap.java +++ b/Ports/CLDC11/src/java/util/NavigableMap.java @@ -16,247 +16,297 @@ package java.util; -/** - * NavigableMap is a SortedMap with navigation methods answering the closest - * matches for specified item. - * - * @param - * the type of key - * @param - * the type of value - * @since 1.6 - */ +/// NavigableMap is a SortedMap with navigation methods answering the closest +/// matches for specified item. +/// +/// @param +/// the type of key +/// @param +/// the type of value +/// +/// #### Since +/// +/// 1.6 public interface NavigableMap extends SortedMap { - /** - * Answers the entry with the smallest key, or null if the map is empty. - * - * @return the entry with the smallest key, or null if the map is empty - */ + /// Answers the entry with the smallest key, or null if the map is empty. + /// + /// #### Returns + /// + /// the entry with the smallest key, or null if the map is empty Map.Entry firstEntry(); - /** - * Answers the entry with the biggest key, or null if the map is empty. - * - * @return the entry with the biggest key, or null if the map is empty - */ + /// Answers the entry with the biggest key, or null if the map is empty. + /// + /// #### Returns + /// + /// the entry with the biggest key, or null if the map is empty Map.Entry lastEntry(); - /** - * Deletes and answers the entry with the smallest key, or null if the map - * is empty. - * - * @return the entry with the smallest key, or null if the map is empty - */ + /// Deletes and answers the entry with the smallest key, or null if the map + /// is empty. + /// + /// #### Returns + /// + /// the entry with the smallest key, or null if the map is empty Map.Entry pollFirstEntry(); - /** - * Deletes and answers the entry with the biggest key, or null if the map is - * empty. - * - * @return the entry with the biggest key, or null if the map is empty - */ + /// Deletes and answers the entry with the biggest key, or null if the map is + /// empty. + /// + /// #### Returns + /// + /// the entry with the biggest key, or null if the map is empty Map.Entry pollLastEntry(); - /** - * Answers an entry related with the smallest key greater than or equal to - * the specified key, or null if no such key. - * - * @param key - * the key - * @return the entry, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers an entry related with the smallest key greater than or equal to + /// the specified key, or null if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the entry, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key Map.Entry ceilingEntry(K key); - /** - * Answers the smallest key greater than or equal to the specified key, or - * null if no such key. - * - * @param key - * the key - * @return the smallest key greater than or equal to key, or null if no such - * key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers the smallest key greater than or equal to the specified key, or + /// null if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// @return the smallest key greater than or equal to key, or null if no such + /// key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key K ceilingKey(K key); - /** - * Answers an entry related with the smallest key greater than the specified - * key, or null if no such key. - * - * @param key - * the key - * @return the entry, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers an entry related with the smallest key greater than the specified + /// key, or null if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the entry, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key Map.Entry higherEntry(K key); - /** - * Answers the smallest key greater than the specified key, or null if no - * such key. - * - * @param key - * the key - * @return the smallest key greater than key, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers the smallest key greater than the specified key, or null if no + /// such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the smallest key greater than key, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key K higherKey(K key); - /** - * Answers an entry related with the biggest key less than or equal to the - * specified key, or null if no such key. - * - * @param key - * the key - * @return the entry, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers an entry related with the biggest key less than or equal to the + /// specified key, or null if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the entry, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key Map.Entry floorEntry(K key); - /** - * Answers the biggest key less than or equal to the specified key, or null - * if no such key. - * - * @param key - * the key - * @return the biggest key less than or equal to key, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers the biggest key less than or equal to the specified key, or null + /// if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the biggest key less than or equal to key, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key K floorKey(K key); - /** - * Answers an entry related with the biggest key less than the specified - * key, or null if no such key. - * - * @param key - * the key - * @return the entry, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers an entry related with the biggest key less than the specified + /// key, or null if no such key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the entry, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key Map.Entry lowerEntry(K key); - /** - * Answers the biggest key less than the specified key, or null if no such - * key. - * - * @param key - * the key - * @return the biggest key less than key, or null if no such key - * @throws ClassCastException - * if the key cannot be compared with the keys in the map - * @throws NullPointerException - * if the key is null and the map can not contain null key - */ + /// Answers the biggest key less than the specified key, or null if no such + /// key. + /// + /// #### Parameters + /// + /// - `key`: the key + /// + /// #### Returns + /// + /// the biggest key less than key, or null if no such key + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in the map + /// + /// - `NullPointerException`: if the key is null and the map can not contain null key K lowerKey(K key); - /** - * Answers a NavigableSet view of the keys in ascending order. - * - * @return the navigable set view - */ + /// Answers a NavigableSet view of the keys in ascending order. + /// + /// #### Returns + /// + /// the navigable set view NavigableSet navigableKeySet(); - /** - * Answers a reverse order view of the map. - * - * @return the reverse order view of the map - */ + /// Answers a reverse order view of the map. + /// + /// #### Returns + /// + /// the reverse order view of the map NavigableMap descendingMap(); - /** - * Answers a NavigableSet view of the keys in descending order. - * - * @return the navigable set view - */ + /// Answers a NavigableSet view of the keys in descending order. + /// + /// #### Returns + /// + /// the navigable set view NavigableSet descendingKeySet(); - /** - * Answers a view of part of the map whose keys is from startKey to endKey. - * - * @param startKey - * the start key - * @param startInclusive - * true if the start key is in the returned map - * @param endKey - * the end key - * @param endInclusive - * true if the end key is in the returned map - * @return the sub-map view - * - * @exception ClassCastException - * when the class of the start or end key is inappropriate - * for this SubMap - * @exception NullPointerException - * when the start or end key is null and this SortedMap does - * not support null keys - * @exception IllegalArgumentException - * when the start key is greater than the end key - */ + /// Answers a view of part of the map whose keys is from startKey to endKey. + /// + /// #### Parameters + /// + /// - `startKey`: the start key + /// + /// - `startInclusive`: true if the start key is in the returned map + /// + /// - `endKey`: the end key + /// + /// - `endInclusive`: true if the end key is in the returned map + /// + /// #### Returns + /// + /// the sub-map view + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the class of the start or end key is inappropriate + /// for this SubMap + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the start or end key is null and this SortedMap does + /// not support null keys + /// + /// - `IllegalArgumentException`: when the start key is greater than the end key NavigableMap subMap(K startKey, boolean startInclusive, K endKey, boolean endInclusive); - /** - * Answers a view of the head of the map whose keys are smaller than (or - * equal to, depends on inclusive argument) endKey. - * - * @param endKey - * the end key - * @param inclusive - * true if the end key is in the returned map - * @return the head-map view - * - * @exception ClassCastException - * when the class of the end key is inappropriate for this - * SubMap - * @exception NullPointerException - * when the end key is null and this SortedMap does not - * support null keys - * @exception IllegalArgumentException - * when the map is range-limited and end key is out of the - * range of the map - */ + /// Answers a view of the head of the map whose keys are smaller than (or + /// equal to, depends on inclusive argument) endKey. + /// + /// #### Parameters + /// + /// - `endKey`: the end key + /// + /// - `inclusive`: true if the end key is in the returned map + /// + /// #### Returns + /// + /// the head-map view + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the class of the end key is inappropriate for this + /// SubMap + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the end key is null and this SortedMap does not + /// support null keys + /// + /// - `IllegalArgumentException`: @exception IllegalArgumentException + /// when the map is range-limited and end key is out of the + /// range of the map NavigableMap headMap(K endKey, boolean inclusive); - /** - * Answers a view of the tail of the map whose keys are bigger than (or - * equal to, depends on inclusive argument) startKey. - * - * @param startKey - * the start key - * @param inclusive - * true if the start key is in the returned map - * @return the tail-map view - * - * @exception ClassCastException - * when the class of the start key is inappropriate for this - * SubMap - * @exception NullPointerException - * when the start key is null and this SortedMap does not - * support null keys - * @exception IllegalArgumentException - * when the map is range-limited and start key is out of the - * range of the map - */ + /// Answers a view of the tail of the map whose keys are bigger than (or + /// equal to, depends on inclusive argument) startKey. + /// + /// #### Parameters + /// + /// - `startKey`: the start key + /// + /// - `inclusive`: true if the start key is in the returned map + /// + /// #### Returns + /// + /// the tail-map view + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the class of the start key is inappropriate for this + /// SubMap + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the start key is null and this SortedMap does not + /// support null keys + /// + /// - `IllegalArgumentException`: @exception IllegalArgumentException + /// when the map is range-limited and start key is out of the + /// range of the map NavigableMap tailMap(K startKey, boolean inclusive); } diff --git a/Ports/CLDC11/src/java/util/NavigableSet.java b/Ports/CLDC11/src/java/util/NavigableSet.java index 0cff30e10a..981d2e8bb8 100644 --- a/Ports/CLDC11/src/java/util/NavigableSet.java +++ b/Ports/CLDC11/src/java/util/NavigableSet.java @@ -17,176 +17,208 @@ package java.util; -/** - * NavigableSet is a SortedSet with navigation methods answering the closest - * matches for specified item. - * - * @param - * the type of element - * @since 1.6 - */ +/// NavigableSet is a SortedSet with navigation methods answering the closest +/// matches for specified item. +/// +/// @param +/// the type of element +/// +/// #### Since +/// +/// 1.6 public interface NavigableSet extends SortedSet { - /** - * Deletes and answers the smallest element, or null if the set is empty. - * - * @return the smallest element, or null if the set is empty - */ + /// Deletes and answers the smallest element, or null if the set is empty. + /// + /// #### Returns + /// + /// the smallest element, or null if the set is empty E pollFirst(); - /** - * Deletes and answers the biggest element, or null if the set is empty. - * - * @return the biggest element, or null if the set is empty - */ + /// Deletes and answers the biggest element, or null if the set is empty. + /// + /// #### Returns + /// + /// the biggest element, or null if the set is empty E pollLast(); - /** - * Answers the smallest element bigger than the specified one, or null if no - * such element. - * - * @param e - * the specified element - * @return the smallest element bigger than the specified one, or null if no - * such element - * @throws ClassCastException - * if the element cannot be compared with the ones in the set - * @throws NullPointerException - * if the element is null and the set can not contain null - */ + /// Answers the smallest element bigger than the specified one, or null if no + /// such element. + /// + /// #### Parameters + /// + /// - `e`: the specified element + /// + /// #### Returns + /// + /// @return the smallest element bigger than the specified one, or null if no + /// such element + /// + /// #### Throws + /// + /// - `ClassCastException`: if the element cannot be compared with the ones in the set + /// + /// - `NullPointerException`: if the element is null and the set can not contain null E higher(E e); - /** - * Answers the smallest element bigger than or equal to the specified one, - * or null if no such element. - * - * @param e - * the specified element - * @return the smallest element bigger than or equal to the specified one, - * or null if no such element - * @throws ClassCastException - * if the element cannot be compared with the ones in the set - * @throws NullPointerException - * if the element is null and the set can not contain null - */ + /// Answers the smallest element bigger than or equal to the specified one, + /// or null if no such element. + /// + /// #### Parameters + /// + /// - `e`: the specified element + /// + /// #### Returns + /// + /// @return the smallest element bigger than or equal to the specified one, + /// or null if no such element + /// + /// #### Throws + /// + /// - `ClassCastException`: if the element cannot be compared with the ones in the set + /// + /// - `NullPointerException`: if the element is null and the set can not contain null E ceiling(E e); - /** - * Answers the biggest element less than the specified one, or null if no - * such element. - * - * @param e - * the specified element - * @return the biggest element less than the specified one, or null if no - * such element - * @throws ClassCastException - * if the element cannot be compared with the ones in the set - * @throws NullPointerException - * if the element is null and the set can not contain null - */ + /// Answers the biggest element less than the specified one, or null if no + /// such element. + /// + /// #### Parameters + /// + /// - `e`: the specified element + /// + /// #### Returns + /// + /// @return the biggest element less than the specified one, or null if no + /// such element + /// + /// #### Throws + /// + /// - `ClassCastException`: if the element cannot be compared with the ones in the set + /// + /// - `NullPointerException`: if the element is null and the set can not contain null E lower(E e); - /** - * Answers the biggest element less than or equal to the specified one, or - * null if no such element. - * - * @param e - * the specified element - * @return the biggest element less than or equal to the specified one, or - * null if no such element - * @throws ClassCastException - * if the element cannot be compared with the ones in the set - * @throws NullPointerException - * if the element is null and the set can not contain null - */ + /// Answers the biggest element less than or equal to the specified one, or + /// null if no such element. + /// + /// #### Parameters + /// + /// - `e`: the specified element + /// + /// #### Returns + /// + /// @return the biggest element less than or equal to the specified one, or + /// null if no such element + /// + /// #### Throws + /// + /// - `ClassCastException`: if the element cannot be compared with the ones in the set + /// + /// - `NullPointerException`: if the element is null and the set can not contain null E floor(E e); - /** - * Answers a descending iterator of this set. - * - * @return the descending iterator - */ + /// Answers a descending iterator of this set. + /// + /// #### Returns + /// + /// the descending iterator Iterator descendingIterator(); - /** - * Answers a reverse order view of this set. - * - * @return the reverse order view - */ + /// Answers a reverse order view of this set. + /// + /// #### Returns + /// + /// the reverse order view NavigableSet descendingSet(); - /** - * Answers a NavigableSet of the specified portion of this set which - * contains elements greater (or equal to, depends on startInclusive) the - * start element but less than (or equal to, depends on endInclusive) the - * end element. The returned NavigableSet is backed by this set so changes - * to one are reflected by the other. - * - * @param start - * the start element - * @param startInclusive - * true if the start element is in the returned set - * @param end - * the end element - * @param endInclusive - * true if the end element is in the returned set - * @return the subset - * - * @throws ClassCastException - * when the start or end object cannot be compared with the - * elements in this set - * @throws NullPointerException - * when the start or end object is null and the set cannot - * contain null - * @throws IllegalArgumentException - * when the start is bigger than end; or start or end is out of - * range and the set has a range - */ + /// Answers a NavigableSet of the specified portion of this set which + /// contains elements greater (or equal to, depends on startInclusive) the + /// start element but less than (or equal to, depends on endInclusive) the + /// end element. The returned NavigableSet is backed by this set so changes + /// to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the start element + /// + /// - `startInclusive`: true if the start element is in the returned set + /// + /// - `end`: the end element + /// + /// - `endInclusive`: true if the end element is in the returned set + /// + /// #### Returns + /// + /// the subset + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the start or end object cannot be compared with the + /// elements in this set + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the start or end object is null and the set cannot + /// contain null + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// when the start is bigger than end; or start or end is out of + /// range and the set has a range NavigableSet subSet(E start, boolean startInclusive, E end, boolean endInclusive); - /** - * Answers a NavigableSet of the specified portion of this set which - * contains elements less than (or equal to, depends on endInclusive) the - * end element. The returned NavigableSet is backed by this set so changes - * to one are reflected by the other. - * - * @param end - * the end element - * @param endInclusive - * true if the end element is in the returned set - * @return the subset - * - * @throws ClassCastException - * when the end object cannot be compared with the elements in - * this set - * @throws NullPointerException - * when the end object is null and the set cannot contain handle - * null - * @throws IllegalArgumentException - * when end is out of range and the set has a range - */ + /// Answers a NavigableSet of the specified portion of this set which + /// contains elements less than (or equal to, depends on endInclusive) the + /// end element. The returned NavigableSet is backed by this set so changes + /// to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `end`: the end element + /// + /// - `endInclusive`: true if the end element is in the returned set + /// + /// #### Returns + /// + /// the subset + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the end object cannot be compared with the elements in + /// this set + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the end object is null and the set cannot contain handle + /// null + /// + /// - `IllegalArgumentException`: when end is out of range and the set has a range NavigableSet headSet(E end, boolean endInclusive); - /** - * Answers a NavigableSet of the specified portion of this set which - * contains elements greater (or equal to, depends on startInclusive) the - * start element. The returned NavigableSet is backed by this set so changes - * to one are reflected by the other. - * - * @param start - * the start element - * @param startInclusive - * true if the start element is in the returned set - * @return the subset - * - * @throws ClassCastException - * when the start object cannot be compared with the elements in - * this set - * @throws NullPointerException - * when the start object is null and the set cannot contain null - * @throws IllegalArgumentException - * when start is out of range and the set has a range - */ + /// Answers a NavigableSet of the specified portion of this set which + /// contains elements greater (or equal to, depends on startInclusive) the + /// start element. The returned NavigableSet is backed by this set so changes + /// to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the start element + /// + /// - `startInclusive`: true if the start element is in the returned set + /// + /// #### Returns + /// + /// the subset + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the start object cannot be compared with the elements in + /// this set + /// + /// - `NullPointerException`: when the start object is null and the set cannot contain null + /// + /// - `IllegalArgumentException`: when start is out of range and the set has a range NavigableSet tailSet(E start, boolean startInclusive); } diff --git a/Ports/CLDC11/src/java/util/NoSuchElementException.java b/Ports/CLDC11/src/java/util/NoSuchElementException.java index c497443034..6dcd013d4e 100644 --- a/Ports/CLDC11/src/java/util/NoSuchElementException.java +++ b/Ports/CLDC11/src/java/util/NoSuchElementException.java @@ -22,22 +22,16 @@ * have any questions. */ package java.util; -/** - * Thrown by the nextElement method of an Enumeration to indicate that there are no more elements in the enumeration. - * Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:Enumeration, Enumeration.nextElement() - */ +/// Thrown by the nextElement method of an Enumeration to indicate that there are no more elements in the enumeration. +/// Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) See Also:Enumeration, Enumeration.nextElement() public class NoSuchElementException extends java.lang.RuntimeException{ - /** - * Constructs a NoSuchElementException with null as its error message string. - */ + /// Constructs a NoSuchElementException with null as its error message string. public NoSuchElementException(){ //TODO codavaj!! } - /** - * Constructs a NoSuchElementException, saving a reference to the error message string s for later retrieval by the getMessage method. - * Parameters:s - the detail message. - */ + /// Constructs a NoSuchElementException, saving a reference to the error message string s for later retrieval by the getMessage method. + /// Parameters:s - the detail message. public NoSuchElementException(java.lang.String s){ //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/util/Objects.java b/Ports/CLDC11/src/java/util/Objects.java index 76a75c5c0d..976f02b021 100644 --- a/Ports/CLDC11/src/java/util/Objects.java +++ b/Ports/CLDC11/src/java/util/Objects.java @@ -26,20 +26,19 @@ package java.util; -/** - * This is a compatibility class which supports the java.util.Objects API. On platforms that don't support this class (e.g. Android) - * the build server will automatically remap all uses of java.util.Objects to use this implementation instead. - * - * This class consists of static utility methods for operating on objects. These utilities include null-safe or null-tolerant methods for computing the hash code of an object, returning a string for an object, and comparing two objects. - * @author shannah - */ +/// This is a compatibility class which supports the java.util.Objects API. On platforms that don't support this class (e.g. Android) +/// the build server will automatically remap all uses of java.util.Objects to use this implementation instead. +/// +/// This class consists of static utility methods for operating on objects. These utilities include null-safe or null-tolerant methods for computing the hash code of an object, returning a string for an object, and comparing two objects. +/// @author shannah public final class Objects { - /** - * Returns true if the arguments are equal to each other and false otherwise. Consequently, if both arguments are null, true is returned and if exactly one argument is null, false is returned. Otherwise, equality is determined by using the equals method of the first argument. - * @param a - * @param b - * @return - */ + /// Returns true if the arguments are equal to each other and false otherwise. Consequently, if both arguments are null, true is returned and if exactly one argument is null, false is returned. Otherwise, equality is determined by using the equals method of the first argument. + /// + /// #### Parameters + /// + /// - `a` + /// + /// - `b` public static boolean equals(Object a, Object b) { if (a == b) { return true; @@ -47,11 +46,11 @@ public static boolean equals(Object a, Object b) { return a == null ? b == null : a.equals(b); } - /** - * Returns the hash code of a non-null argument and 0 for a null argument. - * @param o - * @return - */ + /// Returns the hash code of a non-null argument and 0 for a null argument. + /// + /// #### Parameters + /// + /// - `o` public static int hashCode(Object o) { return o == null ? 0 : o.hashCode(); } diff --git a/Ports/CLDC11/src/java/util/Observable.java b/Ports/CLDC11/src/java/util/Observable.java index a9e178ecee..a4db730067 100644 --- a/Ports/CLDC11/src/java/util/Observable.java +++ b/Ports/CLDC11/src/java/util/Observable.java @@ -17,37 +17,34 @@ package java.util; -/** - * Observable is used to notify a group of Observer objects when a change - * occurs. On creation, the set of observers is empty. After a change occurred, - * the application can call the {@link #notifyObservers()} method. This will - * cause the invocation of the {@code update()} method of all registered - * Observers. The order of invocation is not specified. This implementation will - * call the Observers in the order they registered. Subclasses are completely - * free in what order they call the update methods. - * - * @see Observer - */ +/// Observable is used to notify a group of Observer objects when a change +/// occurs. On creation, the set of observers is empty. After a change occurred, +/// the application can call the `#notifyObservers()` method. This will +/// cause the invocation of the `update()` method of all registered +/// Observers. The order of invocation is not specified. This implementation will +/// call the Observers in the order they registered. Subclasses are completely +/// free in what order they call the update methods. +/// +/// #### See also +/// +/// - Observer public class Observable { List observers = new ArrayList(); boolean changed = false; - /** - * Constructs a new {@code Observable} object. - */ + /// Constructs a new `Observable` object. public Observable() { super(); } - /** - * Adds the specified observer to the list of observers. If it is already - * registered, it is not added a second time. - * - * @param observer - * the Observer to add. - */ + /// Adds the specified observer to the list of observers. If it is already + /// registered, it is not added a second time. + /// + /// #### Parameters + /// + /// - `observer`: the Observer to add. public void addObserver(Observer observer) { if (observer == null) { throw new NullPointerException(); @@ -58,70 +55,62 @@ public void addObserver(Observer observer) { } } - /** - * Clears the changed flag for this {@code Observable}. After calling - * {@code clearChanged()}, {@code hasChanged()} will return {@code false}. - */ + /// Clears the changed flag for this `Observable`. After calling + /// `clearChanged()`, `hasChanged()` will return `false`. protected void clearChanged() { changed = false; } - /** - * Returns the number of observers registered to this {@code Observable}. - * - * @return the number of observers. - */ + /// Returns the number of observers registered to this `Observable`. + /// + /// #### Returns + /// + /// the number of observers. public int countObservers() { return observers.size(); } - /** - * Removes the specified observer from the list of observers. Passing null - * won't do anything. - * - * @param observer - * the observer to remove. - */ + /// Removes the specified observer from the list of observers. Passing null + /// won't do anything. + /// + /// #### Parameters + /// + /// - `observer`: the observer to remove. public synchronized void deleteObserver(Observer observer) { observers.remove(observer); } - /** - * Removes all observers from the list of observers. - */ + /// Removes all observers from the list of observers. public synchronized void deleteObservers() { observers.clear(); } - /** - * Returns the changed flag for this {@code Observable}. - * - * @return {@code true} when the changed flag for this {@code Observable} is - * set, {@code false} otherwise. - */ + /// Returns the changed flag for this `Observable`. + /// + /// #### Returns + /// + /// @return `true` when the changed flag for this `Observable` is + /// set, `false` otherwise. public boolean hasChanged() { return changed; } - /** - * If {@code hasChanged()} returns {@code true}, calls the {@code update()} - * method for every observer in the list of observers using null as the - * argument. Afterwards, calls {@code clearChanged()}. - *

- * Equivalent to calling {@code notifyObservers(null)}. - */ + /// If `hasChanged()` returns `true`, calls the `update()` + /// method for every observer in the list of observers using null as the + /// argument. Afterwards, calls `clearChanged()`. + /// + /// Equivalent to calling `notifyObservers(null)`. public void notifyObservers() { notifyObservers(null); } - /** - * If {@code hasChanged()} returns {@code true}, calls the {@code update()} - * method for every Observer in the list of observers using the specified - * argument. Afterwards calls {@code clearChanged()}. - * - * @param data - * the argument passed to {@code update()}. - */ + /// If `hasChanged()` returns `true`, calls the `update()` + /// method for every Observer in the list of observers using the specified + /// argument. Afterwards calls `clearChanged()`. + /// + /// #### Parameters + /// + /// - `data`: the argument passed to `update()`. @SuppressWarnings("unchecked") public void notifyObservers(Object data) { int size = 0; @@ -141,10 +130,8 @@ public void notifyObservers(Object data) { } } - /** - * Sets the changed flag for this {@code Observable}. After calling - * {@code setChanged()}, {@code hasChanged()} will return {@code true}. - */ + /// Sets the changed flag for this `Observable`. After calling + /// `setChanged()`, `hasChanged()` will return `true`. protected void setChanged() { changed = true; } diff --git a/Ports/CLDC11/src/java/util/Observer.java b/Ports/CLDC11/src/java/util/Observer.java index c398e1bbee..9ca785884c 100644 --- a/Ports/CLDC11/src/java/util/Observer.java +++ b/Ports/CLDC11/src/java/util/Observer.java @@ -18,23 +18,22 @@ package java.util; -/** - * {@code Observer} is the interface to be implemented by objects that - * receive notification of updates on an {@code Observable} object. - * - * @see Observable - */ +/// `Observer` is the interface to be implemented by objects that +/// receive notification of updates on an `Observable` object. +/// +/// #### See also +/// +/// - Observable public interface Observer { - /** - * This method is called if the specified {@code Observable} object's - * {@code notifyObservers} method is called (because the {@code Observable} - * object has been updated. - * - * @param observable - * the {@link Observable} object. - * @param data - * the data passed to {@link Observable#notifyObservers(Object)}. - */ + /// This method is called if the specified `Observable` object's + /// `notifyObservers` method is called (because the `Observable` + /// object has been updated. + /// + /// #### Parameters + /// + /// - `observable`: the `Observable` object. + /// + /// - `data`: the data passed to `Observable#notifyObservers(Object)`. void update(Observable observable, Object data); } diff --git a/Ports/CLDC11/src/java/util/PriorityQueue.java b/Ports/CLDC11/src/java/util/PriorityQueue.java index 773180b848..311043caf3 100644 --- a/Ports/CLDC11/src/java/util/PriorityQueue.java +++ b/Ports/CLDC11/src/java/util/PriorityQueue.java @@ -15,18 +15,16 @@ */ package java.util; -/** - * A PriorityQueue holds elements on a priority heap, which orders the elements - * according to their natural order or according to the comparator specified at - * construction time. If the queue uses natural ordering, only elements that are - * comparable are permitted to be inserted into the queue. - *

- * The least element of the specified ordering is stored at the head of the - * queue and the greatest element is stored at the tail of the queue. - *

- * A PriorityQueue is not synchronized. If multiple threads will have to access - * it concurrently, use the {@link java.util.concurrent.PriorityBlockingQueue}. - */ +/// A PriorityQueue holds elements on a priority heap, which orders the elements +/// according to their natural order or according to the comparator specified at +/// construction time. If the queue uses natural ordering, only elements that are +/// comparable are permitted to be inserted into the queue. +/// +/// The least element of the specified ordering is stored at the head of the +/// queue and the greatest element is stored at the tail of the queue. +/// +/// A PriorityQueue is not synchronized. If multiple threads will have to access +/// it concurrently, use the `java.util.concurrent.PriorityBlockingQueue`. public class PriorityQueue extends AbstractQueue { private static final int DEFAULT_CAPACITY = 11; @@ -41,38 +39,39 @@ public class PriorityQueue extends AbstractQueue { private transient E[] elements; - /** - * Constructs a priority queue with an initial capacity of 11 and natural - * ordering. - */ + /// Constructs a priority queue with an initial capacity of 11 and natural + /// ordering. public PriorityQueue() { this(DEFAULT_CAPACITY); } - /** - * Constructs a priority queue with the specified capacity and natural - * ordering. - * - * @param initialCapacity - * the specified capacity. - * @throws IllegalArgumentException - * if the initialCapacity is less than 1. - */ + /// Constructs a priority queue with the specified capacity and natural + /// ordering. + /// + /// #### Parameters + /// + /// - `initialCapacity`: the specified capacity. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if the initialCapacity is less than 1. public PriorityQueue(int initialCapacity) { this(initialCapacity, null); } - /** - * Constructs a priority queue with the specified capacity and comparator. - * - * @param initialCapacity - * the specified capacity. - * @param comparator - * the specified comparator. If it is null, the natural ordering - * will be used. - * @throws IllegalArgumentException - * if the initialCapacity is less than 1. - */ + /// Constructs a priority queue with the specified capacity and comparator. + /// + /// #### Parameters + /// + /// - `initialCapacity`: the specified capacity. + /// + /// - `comparator`: @param comparator + /// the specified comparator. If it is null, the natural ordering + /// will be used. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if the initialCapacity is less than 1. public PriorityQueue(int initialCapacity, Comparator comparator) { if (initialCapacity < 1) { throw new IllegalArgumentException(); @@ -81,20 +80,22 @@ public PriorityQueue(int initialCapacity, Comparator comparator) { this.comparator = comparator; } - /** - * Constructs a priority queue that contains the elements of a collection. - * The constructed priority queue has the initial capacity of 110% of the - * size of the collection. The queue uses natural ordering to order its - * elements. - * - * @param c - * the collection whose elements will be added to the priority - * queue to be constructed. - * @throws ClassCastException - * if any of the elements in the collection are not comparable. - * @throws NullPointerException - * if any of the elements in the collection are null. - */ + /// Constructs a priority queue that contains the elements of a collection. + /// The constructed priority queue has the initial capacity of 110% of the + /// size of the collection. The queue uses natural ordering to order its + /// elements. + /// + /// #### Parameters + /// + /// - `c`: @param c + /// the collection whose elements will be added to the priority + /// queue to be constructed. + /// + /// #### Throws + /// + /// - `ClassCastException`: if any of the elements in the collection are not comparable. + /// + /// - `NullPointerException`: if any of the elements in the collection are null. public PriorityQueue(Collection c) { if (c instanceof PriorityQueue) { getFromPriorityQueue((PriorityQueue) c); @@ -106,77 +107,80 @@ public PriorityQueue(Collection c) { } } - /** - * Constructs a priority queue that contains the elements of another - * priority queue. The constructed priority queue has the initial capacity - * of 110% of the specified one. Both priority queues have the same - * comparator. - * - * @param c - * the priority queue whose elements will be added to the - * priority queue to be constructed. - */ + /// Constructs a priority queue that contains the elements of another + /// priority queue. The constructed priority queue has the initial capacity + /// of 110% of the specified one. Both priority queues have the same + /// comparator. + /// + /// #### Parameters + /// + /// - `c`: @param c + /// the priority queue whose elements will be added to the + /// priority queue to be constructed. public PriorityQueue(PriorityQueue c) { getFromPriorityQueue(c); } - /** - * Constructs a priority queue that contains the elements of a sorted set. - * The constructed priority queue has the initial capacity of 110% of the - * size of the sorted set. The priority queue will have the same comparator - * as the sorted set. - * - * @param c - * the sorted set whose elements will be added to the priority - * queue to be constructed. - */ + /// Constructs a priority queue that contains the elements of a sorted set. + /// The constructed priority queue has the initial capacity of 110% of the + /// size of the sorted set. The priority queue will have the same comparator + /// as the sorted set. + /// + /// #### Parameters + /// + /// - `c`: @param c + /// the sorted set whose elements will be added to the priority + /// queue to be constructed. public PriorityQueue(SortedSet c) { getFromSortedSet(c); } - /** - * Gets the iterator of the priority queue, which will not return elements - * in any specified ordering. - * - * @return the iterator of the priority queue. - */ + /// Gets the iterator of the priority queue, which will not return elements + /// in any specified ordering. + /// + /// #### Returns + /// + /// the iterator of the priority queue. @Override public Iterator iterator() { return new PriorityIterator(); } - /** - * Gets the size of the priority queue. If the size of the queue is greater - * than the Integer.MAX, then it returns Integer.MAX. - * - * @return the size of the priority queue. - */ + /// Gets the size of the priority queue. If the size of the queue is greater + /// than the Integer.MAX, then it returns Integer.MAX. + /// + /// #### Returns + /// + /// the size of the priority queue. @Override public int size() { return size; } - /** - * Removes all the elements of the priority queue. - */ + /// Removes all the elements of the priority queue. @Override public void clear() { Arrays.fill(elements, null); size = 0; } - /** - * Inserts the element to the priority queue. - * - * @param o - * the element to add to the priority queue. - * @return always true - * @throws ClassCastException - * if the element cannot be compared with the elements in the - * priority queue using the ordering of the priority queue. - * @throws NullPointerException - * if {@code o} is {@code null}. - */ + /// Inserts the element to the priority queue. + /// + /// #### Parameters + /// + /// - `o`: the element to add to the priority queue. + /// + /// #### Returns + /// + /// always true + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the element cannot be compared with the elements in the + /// priority queue using the ordering of the priority queue. + /// + /// - `NullPointerException`: if `o` is `null`. public boolean offer(E o) { if (null == o) { throw new NullPointerException(); @@ -187,11 +191,11 @@ public boolean offer(E o) { return true; } - /** - * Gets and removes the head of the queue. - * - * @return the head of the queue or null if the queue is empty. - */ + /// Gets and removes the head of the queue. + /// + /// #### Returns + /// + /// the head of the queue or null if the queue is empty. public E poll() { if (isEmpty()) { return null; @@ -201,11 +205,11 @@ public E poll() { return result; } - /** - * Gets but does not remove the head of the queue. - * - * @return the head of the queue or null if the queue is empty. - */ + /// Gets but does not remove the head of the queue. + /// + /// #### Returns + /// + /// the head of the queue or null if the queue is empty. public E peek() { if (isEmpty()) { return null; @@ -213,24 +217,26 @@ public E peek() { return elements[0]; } - /** - * Gets the comparator of the priority queue. - * - * @return the comparator of the priority queue or null if the natural - * ordering is used. - */ + /// Gets the comparator of the priority queue. + /// + /// #### Returns + /// + /// @return the comparator of the priority queue or null if the natural + /// ordering is used. public Comparator comparator() { return comparator; } - /** - * Removes the specified object from the priority queue. - * - * @param o - * the object to be removed. - * @return true if the object was in the priority queue, false if the object - * was not in the priority queue. - */ + /// Removes the specified object from the priority queue. + /// + /// #### Parameters + /// + /// - `o`: the object to be removed. + /// + /// #### Returns + /// + /// @return true if the object was in the priority queue, false if the object + /// was not in the priority queue. @Override public boolean remove(Object o) { if (o == null || size == 0) { @@ -245,28 +251,33 @@ public boolean remove(Object o) { return false; } - /** - * Adds the specified object to the priority queue. - * - * @param o - * the object to be added. - * @return always true. - * @throws ClassCastException - * if the element cannot be compared with the elements in the - * priority queue using the ordering of the priority queue. - * @throws NullPointerException - * if {@code o} is {@code null}. - */ + /// Adds the specified object to the priority queue. + /// + /// #### Parameters + /// + /// - `o`: the object to be added. + /// + /// #### Returns + /// + /// always true. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the element cannot be compared with the elements in the + /// priority queue using the ordering of the priority queue. + /// + /// - `NullPointerException`: if `o` is `null`. @Override public boolean add(E o) { return offer(o); } - /** - * Answers if there is an element in this queue equals to the object. - * - * @see java.util.AbstractCollection#contains(java.lang.Object) - */ + /// Answers if there is an element in this queue equals to the object. + /// + /// #### See also + /// + /// - java.util.AbstractCollection#contains(java.lang.Object) @Override public boolean contains(Object object) { if (object == null) { @@ -280,40 +291,53 @@ public boolean contains(Object object) { return false; } - /** - * Returns all the elements in an array. The result is a copy of all the - * elements. - * - * @return the Array of all the elements - * @see java.util.AbstractCollection#toArray() - */ + /// Returns all the elements in an array. The result is a copy of all the + /// elements. + /// + /// #### Returns + /// + /// the Array of all the elements + /// + /// #### See also + /// + /// - java.util.AbstractCollection#toArray() @Override public Object[] toArray() { return newArray(new Object[size()]); } - /** - * Returns all the elements in an array, and the type of the result array is - * the type of the argument array. If the argument array is big enough, the - * elements from the queue will be stored in it(element immediately - * following the end of the queue is set to null, if any); otherwise, it - * will return a new array with the size of the argument array and size of - * the queue. - * - * @param - * the type of elements in the array - * @param array - * the array stores all the elements from the queue, if it has - * enough space; otherwise, a new array of the same type and the - * size of the queue will be used - * @return the Array of all the elements - * @throws ArrayStoreException - * if the type of the argument array is not compatible with - * every element in the queue - * @throws NullPointerException - * if the argument array is null - * @see java.util.AbstractCollection#toArray(T[]) - */ + /// Returns all the elements in an array, and the type of the result array is + /// the type of the argument array. If the argument array is big enough, the + /// elements from the queue will be stored in it(element immediately + /// following the end of the queue is set to null, if any); otherwise, it + /// will return a new array with the size of the argument array and size of + /// the queue. + /// + /// @param + /// the type of elements in the array + /// + /// #### Parameters + /// + /// - `array`: @param array + /// the array stores all the elements from the queue, if it has + /// enough space; otherwise, a new array of the same type and the + /// size of the queue will be used + /// + /// #### Returns + /// + /// the Array of all the elements + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// if the type of the argument array is not compatible with + /// every element in the queue + /// + /// - `NullPointerException`: if the argument array is null + /// + /// #### See also + /// + /// - java.util.AbstractCollection#toArray(T[]) @Override public T[] toArray(T[] array) { return newArray(array); diff --git a/Ports/CLDC11/src/java/util/Queue.java b/Ports/CLDC11/src/java/util/Queue.java index 6ef776a638..306db847aa 100644 --- a/Ports/CLDC11/src/java/util/Queue.java +++ b/Ports/CLDC11/src/java/util/Queue.java @@ -16,76 +16,78 @@ */ package java.util; -/** - * This kind of collection provides advanced operations compared to basic - * collections, such as insertion, extraction, and inspection. - *

- * Generally, a queue orders its elements by means of first-in-first-out. - * However, a priority queue orders its elements according to a comparator - * specified or the elements' natural order. Furthermore, a stack orders its - * elements last-in-first out. - *

- * A typical queue does not allow {@code null} to be inserted as its element, - * while some implementations such as {@code LinkedList} allow it. But {@code - * null} should not be inserted even in these implementations, since the method - * {@code poll} returns {@code null} to indicate that there is no element left - * in the queue. - *

- * {@code Queue} does not provide blocking queue methods, which would block - * until the operation of the method is allowed. See the - * {@link java.util.concurrent.BlockingQueue} interface for information about - * blocking queue methods. - */ +/// This kind of collection provides advanced operations compared to basic +/// collections, such as insertion, extraction, and inspection. +/// +/// Generally, a queue orders its elements by means of first-in-first-out. +/// However, a priority queue orders its elements according to a comparator +/// specified or the elements' natural order. Furthermore, a stack orders its +/// elements last-in-first out. +/// +/// A typical queue does not allow `null` to be inserted as its element, +/// while some implementations such as `LinkedList` allow it. But `null` should not be inserted even in these implementations, since the method +/// `poll` returns `null` to indicate that there is no element left +/// in the queue. +/// +/// `Queue` does not provide blocking queue methods, which would block +/// until the operation of the method is allowed. See the +/// `java.util.concurrent.BlockingQueue` interface for information about +/// blocking queue methods. public interface Queue extends Collection { - /** - * Inserts the specified element into the queue provided that the condition - * allows such an operation. The method is generally preferable to - * {@link Collection#add}, since the latter might throw an exception if the - * operation fails. - * - * @param o - * the specified element to insert into the queue. - * @return {@code true} if the operation succeeds and {@code false} if it - * fails. - */ + /// Inserts the specified element into the queue provided that the condition + /// allows such an operation. The method is generally preferable to + /// `Collection#add`, since the latter might throw an exception if the + /// operation fails. + /// + /// #### Parameters + /// + /// - `o`: the specified element to insert into the queue. + /// + /// #### Returns + /// + /// @return `true` if the operation succeeds and `false` if it + /// fails. public boolean offer(E o); - /** - * Gets and removes the element at the head of the queue, or returns {@code - * null} if there is no element in the queue. - * - * @return the element at the head of the queue or {@code null} if there is - * no element in the queue. - */ + /// Gets and removes the element at the head of the queue, or returns `null` if there is no element in the queue. + /// + /// #### Returns + /// + /// @return the element at the head of the queue or `null` if there is + /// no element in the queue. public E poll(); - /** - * Gets and removes the element at the head of the queue. Throws a - * NoSuchElementException if there is no element in the queue. - * - * @return the element at the head of the queue. - * @throws NoSuchElementException - * if there is no element in the queue. - */ + /// Gets and removes the element at the head of the queue. Throws a + /// NoSuchElementException if there is no element in the queue. + /// + /// #### Returns + /// + /// the element at the head of the queue. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there is no element in the queue. public E remove(); - /** - * Gets but does not remove the element at the head of the queue. - * - * @return the element at the head of the queue or {@code null} if there is - * no element in the queue. - */ + /// Gets but does not remove the element at the head of the queue. + /// + /// #### Returns + /// + /// @return the element at the head of the queue or `null` if there is + /// no element in the queue. public E peek(); - /** - * Gets but does not remove the element at the head of the queue. Throws a - * {@code NoSuchElementException} if there is no element in the queue. - * - * @return the element at the head of the queue. - * @throws NoSuchElementException - * if there is no element in the queue. - */ + /// Gets but does not remove the element at the head of the queue. Throws a + /// `NoSuchElementException` if there is no element in the queue. + /// + /// #### Returns + /// + /// the element at the head of the queue. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if there is no element in the queue. public E element(); } diff --git a/Ports/CLDC11/src/java/util/Random.java b/Ports/CLDC11/src/java/util/Random.java index 171fb9df9c..5ba7aeb1de 100644 --- a/Ports/CLDC11/src/java/util/Random.java +++ b/Ports/CLDC11/src/java/util/Random.java @@ -22,90 +22,70 @@ * have any questions. */ package java.util; -/** - * An instance of this class is used to generate a stream of pseudorandom numbers. The class uses a 48-bit seed, which is modified using a linear congruential formula. (See Donald Knuth, The Art of Computer Programming, Volume 2, Section 3.2.1.) - * If two instances of Random are created with the same seed, and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers. In order to guarantee this property, particular algorithms are specified for the class Random. Java implementations must use all the algorithms shown here for the class Random, for the sake of absolute portability of Java code. However, subclasses of class Random are permitted to use other algorithms, so long as they adhere to the general contracts for all the methods. - * The algorithms implemented by class Random use a protected utility method that on each invocation can supply up to 32 pseudorandomly generated bits. - * Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) - */ +/// An instance of this class is used to generate a stream of pseudorandom numbers. The class uses a 48-bit seed, which is modified using a linear congruential formula. (See Donald Knuth, The Art of Computer Programming, Volume 2, Section 3.2.1.) +/// If two instances of Random are created with the same seed, and the same sequence of method calls is made for each, they will generate and return identical sequences of numbers. In order to guarantee this property, particular algorithms are specified for the class Random. Java implementations must use all the algorithms shown here for the class Random, for the sake of absolute portability of Java code. However, subclasses of class Random are permitted to use other algorithms, so long as they adhere to the general contracts for all the methods. +/// The algorithms implemented by class Random use a protected utility method that on each invocation can supply up to 32 pseudorandomly generated bits. +/// Since: JDK1.0, CLDC 1.0 Version: 12/17/01 (CLDC 1.1) public class Random{ - /** - * Creates a new random number generator. Its seed is initialized to a value based on the current time: public Random() { this(System.currentTimeMillis()); } - * See Also:System.currentTimeMillis() - */ + /// Creates a new random number generator. Its seed is initialized to a value based on the current time: public Random() { this(System.currentTimeMillis()); } + /// See Also:System.currentTimeMillis() public Random(){ //TODO codavaj!! } - /** - * Creates a new random number generator using a single long seed: public Random(long seed) { setSeed(seed); } Used by method next to hold the state of the pseudorandom number generator. - * Parameters:seed - the initial seed.See Also:setSeed(long) - */ + /// Creates a new random number generator using a single long seed: public Random(long seed) { setSeed(seed); } Used by method next to hold the state of the pseudorandom number generator. + /// Parameters:seed - the initial seed.See Also:setSeed(long) public Random(long seed){ //TODO codavaj!! } - /** - * Generates the next pseudorandom number. Subclass should override this, as this is used by all other methods. - * The general contract of next is that it returns an int value and if the argument bits is between 1 and 32 (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be 0 or 1. The method next is implemented by class Random as follows: - * synchronized protected int next(int bits) { seed = (seed * 0x5DEECE66DL + 0xBL) & ((1L << 48) - 1); return (int)(seed >>> (48 - bits)); } This is a linear congruential pseudorandom number generator, as defined by D. H. Lehmer and described by Donald E. Knuth in - * Volume 2: - * , section 3.2.1. - */ + /// Generates the next pseudorandom number. Subclass should override this, as this is used by all other methods. + /// The general contract of next is that it returns an int value and if the argument bits is between 1 and 32 (inclusive), then that many low-order bits of the returned value will be (approximately) independently chosen bit values, each of which is (approximately) equally likely to be 0 or 1. The method next is implemented by class Random as follows: + /// synchronized protected int next(int bits) { seed = (seed * 0x5DEECE66DL + 0xBL) & ((1L >> (48 - bits)); } This is a linear congruential pseudorandom number generator, as defined by D. H. Lehmer and described by Donald E. Knuth in + /// Volume 2: + /// , section 3.2.1. protected int next(int bits){ return 0; //TODO codavaj!! } - /** - * Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence. - * The general contract of nextDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned. All 253 possible float values of the form mx2-53 , where m is a positive integer less than 253, are produced with (approximately) equal probability. The method nextDouble is implemented by class Random as follows: - * public double nextDouble() { return (((long)next(26) << 27) + next(27)) / (double)(1L << 53); } - * The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose double values from the stated range with perfect uniformity. - * [In early versions of Java, the result was incorrectly calculated as: - * return (((long)next(27) << 27) + next(27)) / (double)(1L << 54); This might seem to be equivalent, if not better, but in fact it introduced a large nonuniformity because of the bias in the rounding of floating-point numbers: it was three times as likely that the low-order bit of the significand would be 0 than that it would be 1! This nonuniformity probably doesn't matter much in practice, but we strive for perfection.] - */ + /// Returns the next pseudorandom, uniformly distributed double value between 0.0 and 1.0 from this random number generator's sequence. + /// The general contract of nextDouble is that one double value, chosen (approximately) uniformly from the range 0.0d (inclusive) to 1.0d (exclusive), is pseudorandomly generated and returned. All 253 possible float values of the form mx2-53 , where m is a positive integer less than 253, are produced with (approximately) equal probability. The method nextDouble is implemented by class Random as follows: + /// public double nextDouble() { return (((long)next(26) << 27) + next(27)) / (double)(1L << 53); } + /// The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose double values from the stated range with perfect uniformity. + /// [In early versions of Java, the result was incorrectly calculated as: + /// return (((long)next(27) << 27) + next(27)) / (double)(1L << 54); This might seem to be equivalent, if not better, but in fact it introduced a large nonuniformity because of the bias in the rounding of floating-point numbers: it was three times as likely that the low-order bit of the significand would be 0 than that it would be 1! This nonuniformity probably doesn't matter much in practice, but we strive for perfection.] public double nextDouble(){ return 0.0d; //TODO codavaj!! } - /** - * Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence. - * The general contract of nextFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All 224 possible float values of the form mx 2-24, where m is a positive integer less than 224 , are produced with (approximately) equal probability. The method nextFloat is implemented by class Random as follows: - * public float nextFloat() { return next(24) / ((float)(1 << 24)); } The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose float values from the stated range with perfect uniformity. - * [In early versions of Java, the result was incorrectly calculated as: - * return next(30) / ((float)(1 << 30)); This might seem to be equivalent, if not better, but in fact it introduced a slight nonuniformity because of the bias in the rounding of floating-point numbers: it was slightly more likely that the low-order bit of the significand would be 0 than that it would be 1.] - */ + /// Returns the next pseudorandom, uniformly distributed float value between 0.0 and 1.0 from this random number generator's sequence. + /// The general contract of nextFloat is that one float value, chosen (approximately) uniformly from the range 0.0f (inclusive) to 1.0f (exclusive), is pseudorandomly generated and returned. All 224 possible float values of the form mx 2-24, where m is a positive integer less than 224 , are produced with (approximately) equal probability. The method nextFloat is implemented by class Random as follows: + /// public float nextFloat() { return next(24) / ((float)(1 << 24)); } The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source or randomly chosen bits, then the algorithm shown would choose float values from the stated range with perfect uniformity. + /// [In early versions of Java, the result was incorrectly calculated as: + /// return next(30) / ((float)(1 << 30)); This might seem to be equivalent, if not better, but in fact it introduced a slight nonuniformity because of the bias in the rounding of floating-point numbers: it was slightly more likely that the low-order bit of the significand would be 0 than that it would be 1.] public float nextFloat(){ return 0.0f; //TODO codavaj!! } - /** - * Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability. The method nextInt is implemented by class Random as follows: public int nextInt() { return next(32); } - */ + /// Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general contract of nextInt is that one int value is pseudorandomly generated and returned. All 232 possible int values are produced with (approximately) equal probability. The method nextInt is implemented by class Random as follows: public int nextInt() { return next(32); } public int nextInt(){ return 0; //TODO codavaj!! } - /** - * Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All n possible int values are produced with (approximately) equal probability. The method nextInt(int n) is implemented by class Random as follows: public int nextInt(int n) { if (n<=0) throw new IllegalArgumentException("n must be positive"); if ((n & -n) == n) // i.e., n is a power of 2 return (int)((n * (long)next(31)) >> 31); int bits, val; do { bits = next(31); val = bits % n; } while(bits - val + (n-1) < 0); return val; } - * The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source of randomly chosen bits, then the algorithm shown would choose int values from the stated range with perfect uniformity. - * The algorithm rejects values that would result in an uneven distribution (due to the fact that 2^31 is not divisible by n). The probability of a value being rejected depends on n. The worst case is n=2^30+1, for which the probability of a reject is 1/2, and the expected number of iterations before the loop terminates is 2. - * The algorithm treats the case where n is a power of two specially: it returns the correct number of high-order bits from the underlying pseudo-random number generator. In the absence of special treatment, the correct number of low-order bits would be returned. Linear congruential pseudo-random number generators such as the one implemented by this class are known to have short periods in the sequence of values of their low-order bits. Thus, this special case greatly increases the length of the sequence of values returned by successive calls to this method if n is a small power of two. - */ + /// Returns a pseudorandom, uniformly distributed int value between 0 (inclusive) and the specified value (exclusive), drawn from this random number generator's sequence. The general contract of nextInt is that one int value in the specified range is pseudorandomly generated and returned. All n possible int values are produced with (approximately) equal probability. The method nextInt(int n) is implemented by class Random as follows: public int nextInt(int n) { if (n> 31); int bits, val; do { bits = next(31); val = bits % n; } while(bits - val + (n-1) < 0); return val; } + /// The hedge "approximately" is used in the foregoing description only because the next method is only approximately an unbiased source of independently chosen bits. If it were a perfect source of randomly chosen bits, then the algorithm shown would choose int values from the stated range with perfect uniformity. + /// The algorithm rejects values that would result in an uneven distribution (due to the fact that 2^31 is not divisible by n). The probability of a value being rejected depends on n. The worst case is n=2^30+1, for which the probability of a reject is 1/2, and the expected number of iterations before the loop terminates is 2. + /// The algorithm treats the case where n is a power of two specially: it returns the correct number of high-order bits from the underlying pseudo-random number generator. In the absence of special treatment, the correct number of low-order bits would be returned. Linear congruential pseudo-random number generators such as the one implemented by this class are known to have short periods in the sequence of values of their low-order bits. Thus, this special case greatly increases the length of the sequence of values returned by successive calls to this method if n is a small power of two. public int nextInt(int n){ return 0; //TODO codavaj!! } - /** - * Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned. All 264 possible long values are produced with (approximately) equal probability. The method nextLong is implemented by class Random as follows: public long nextLong() { return ((long)next(32) << 32) + next(32); } - */ + /// Returns the next pseudorandom, uniformly distributed long value from this random number generator's sequence. The general contract of nextLong is that one long value is pseudorandomly generated and returned. All 264 possible long values are produced with (approximately) equal probability. The method nextLong is implemented by class Random as follows: public long nextLong() { return ((long)next(32) << 32) + next(32); } public long nextLong(){ return 0l; //TODO codavaj!! } - /** - * Sets the seed of this random number generator using a single long seed. The general contract of setSeed is that it alters the state of this random number generator object so as to be in exactly the same state as if it had just been created with the argument seed as a seed. The method setSeed is implemented by class Random as follows: synchronized public void setSeed(long seed) { this.seed = (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1); } The implementation of setSeed by class Random happens to use only 48 bits of the given seed. In general, however, an overriding method may use all 64 bits of the long argument as a seed value. - */ + /// Sets the seed of this random number generator using a single long seed. The general contract of setSeed is that it alters the state of this random number generator object so as to be in exactly the same state as if it had just been created with the argument seed as a seed. The method setSeed is implemented by class Random as follows: synchronized public void setSeed(long seed) { this.seed = (seed ^ 0x5DEECE66DL) & ((1L << 48) - 1); } The implementation of setSeed by class Random happens to use only 48 bits of the given seed. In general, however, an overriding method may use all 64 bits of the long argument as a seed value. public void setSeed(long seed){ return; //TODO codavaj!! } diff --git a/Ports/CLDC11/src/java/util/RandomAccess.java b/Ports/CLDC11/src/java/util/RandomAccess.java index 7121bff5c8..54f5e63bb0 100644 --- a/Ports/CLDC11/src/java/util/RandomAccess.java +++ b/Ports/CLDC11/src/java/util/RandomAccess.java @@ -17,10 +17,8 @@ package java.util; -/** - * RandomAccess is implemented by {@code List} implementations that support fast - * (usually constant time) random access. - */ +/// RandomAccess is implemented by `List` implementations that support fast +/// (usually constant time) random access. public interface RandomAccess { /* empty */ } diff --git a/Ports/CLDC11/src/java/util/Set.java b/Ports/CLDC11/src/java/util/Set.java index 109c8df1ae..bee049dc4e 100644 --- a/Ports/CLDC11/src/java/util/Set.java +++ b/Ports/CLDC11/src/java/util/Set.java @@ -18,179 +18,227 @@ package java.util; -/** - * A {@code Set} is a data structure which does not allow duplicate elements. - * - * @since 1.2 - */ +/// A `Set` is a data structure which does not allow duplicate elements. +/// +/// #### Since +/// +/// 1.2 public interface Set extends Collection { - /** - * Adds the specified object to this set. The set is not modified if it - * already contains the object. - * - * @param object - * the object to add. - * @return {@code true} if this set is modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * when adding to this set is not supported. - * @throws ClassCastException - * when the class of the object is inappropriate for this set. - * @throws IllegalArgumentException - * when the object cannot be added to this set. - */ + /// Adds the specified object to this set. The set is not modified if it + /// already contains the object. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// `true` if this set is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when adding to this set is not supported. + /// + /// - `ClassCastException`: when the class of the object is inappropriate for this set. + /// + /// - `IllegalArgumentException`: when the object cannot be added to this set. public boolean add(E object); - /** - * Adds the objects in the specified collection which do not exist yet in - * this set. - * - * @param collection - * the collection of objects. - * @return {@code true} if this set is modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * when adding to this set is not supported. - * @throws ClassCastException - * when the class of an object is inappropriate for this set. - * @throws IllegalArgumentException - * when an object cannot be added to this set. - */ + /// Adds the objects in the specified collection which do not exist yet in + /// this set. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// `true` if this set is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when adding to this set is not supported. + /// + /// - `ClassCastException`: when the class of an object is inappropriate for this set. + /// + /// - `IllegalArgumentException`: when an object cannot be added to this set. public boolean addAll(Collection collection); - /** - * Removes all elements from this set, leaving it empty. - * - * @throws UnsupportedOperationException - * when removing from this set is not supported. - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this set, leaving it empty. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when removing from this set is not supported. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size public void clear(); - /** - * Searches this set for the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if object is an element of this set, {@code false} - * otherwise. - */ + /// Searches this set for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if object is an element of this set, `false` + /// otherwise. public boolean contains(Object object); - /** - * Searches this set for all objects in the specified collection. - * - * @param collection - * the collection of objects. - * @return {@code true} if all objects in the specified collection are - * elements of this set, {@code false} otherwise. - */ + /// Searches this set for all objects in the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if all objects in the specified collection are + /// elements of this set, `false` otherwise. public boolean containsAll(Collection collection); - /** - * Compares the specified object to this set, and returns true if they - * represent the same object using a class specific comparison. - * Equality for a set means that both sets have the same size and the same - * elements. - * - * @param object - * the object to compare with this object. - * @return boolean {@code true} if the object is the same as this object, - * and {@code false} if it is different from this object. - * @see #hashCode - */ + /// Compares the specified object to this set, and returns true if they + /// represent the *same* object using a class specific comparison. + /// Equality for a set means that both sets have the same size and the same + /// elements. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object. + /// + /// #### Returns + /// + /// @return boolean `true` if the object is the same as this object, + /// and `false` if it is different from this object. + /// + /// #### See also + /// + /// - #hashCode public boolean equals(Object object); - /** - * Returns the hash code for this set. Two set which are equal must return - * the same value. - * - * @return the hash code of this set. - * - * @see #equals - */ + /// Returns the hash code for this set. Two set which are equal must return + /// the same value. + /// + /// #### Returns + /// + /// the hash code of this set. + /// + /// #### See also + /// + /// - #equals public int hashCode(); - /** - * Returns true if this set has no elements. - * - * @return {@code true} if this set has no elements, {@code false} - * otherwise. - * @see #size - */ + /// Returns true if this set has no elements. + /// + /// #### Returns + /// + /// @return `true` if this set has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size public boolean isEmpty(); - /** - * Returns an iterator on the elements of this set. The elements are - * unordered. - * - * @return an iterator on the elements of this set. - * @see Iterator - */ + /// Returns an iterator on the elements of this set. The elements are + /// unordered. + /// + /// #### Returns + /// + /// an iterator on the elements of this set. + /// + /// #### See also + /// + /// - Iterator public Iterator iterator(); - /** - * Removes the specified object from this set. - * - * @param object - * the object to remove. - * @return {@code true} if this set was modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * when removing from this set is not supported. - */ + /// Removes the specified object from this set. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// `true` if this set was modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when removing from this set is not supported. public boolean remove(Object object); - /** - * Removes all objects in the specified collection from this set. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this set was modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * when removing from this set is not supported. - */ + /// Removes all objects in the specified collection from this set. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// `true` if this set was modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when removing from this set is not supported. public boolean removeAll(Collection collection); - /** - * Removes all objects from this set that are not contained in the specified - * collection. - * - * @param collection - * the collection of objects to retain. - * @return {@code true} if this set was modified, {@code false} otherwise. - * @throws UnsupportedOperationException - * when removing from this set is not supported. - */ + /// Removes all objects from this set that are not contained in the specified + /// collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to retain. + /// + /// #### Returns + /// + /// `true` if this set was modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `UnsupportedOperationException`: when removing from this set is not supported. public boolean retainAll(Collection collection); - /** - * Returns the number of elements in this set. - * - * @return the number of elements in this set. - */ + /// Returns the number of elements in this set. + /// + /// #### Returns + /// + /// the number of elements in this set. public int size(); - /** - * Returns an array containing all elements contained in this set. - * - * @return an array of the elements from this set. - */ + /// Returns an array containing all elements contained in this set. + /// + /// #### Returns + /// + /// an array of the elements from this set. public Object[] toArray(); - /** - * Returns an array containing all elements contained in this set. If the - * specified array is large enough to hold the elements, the specified array - * is used, otherwise an array of the same type is created. If the specified - * array is used and is larger than this set, the array element following - * the collection elements is set to null. - * - * @param array - * the array. - * @return an array of the elements from this set. - * @throws ArrayStoreException - * when the type of an element in this set cannot be stored in - * the type of the specified array. - * @see Collection#toArray(Object[]) - */ + /// Returns an array containing all elements contained in this set. If the + /// specified array is large enough to hold the elements, the specified array + /// is used, otherwise an array of the same type is created. If the specified + /// array is used and is larger than this set, the array element following + /// the collection elements is set to null. + /// + /// #### Parameters + /// + /// - `array`: the array. + /// + /// #### Returns + /// + /// an array of the elements from this set. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// when the type of an element in this set cannot be stored in + /// the type of the specified array. + /// + /// #### See also + /// + /// - Collection#toArray(Object[]) public T[] toArray(T[] array); } diff --git a/Ports/CLDC11/src/java/util/SortedMap.java b/Ports/CLDC11/src/java/util/SortedMap.java index 2fb25fd077..3c5582b8e8 100644 --- a/Ports/CLDC11/src/java/util/SortedMap.java +++ b/Ports/CLDC11/src/java/util/SortedMap.java @@ -18,108 +18,131 @@ package java.util; -/** - * A map that has its keys ordered. The sorting is according to either the - * natural ordering of its keys or the ordering given by a specified comparator. - */ +/// A map that has its keys ordered. The sorting is according to either the +/// natural ordering of its keys or the ordering given by a specified comparator. public interface SortedMap extends Map { - /** - * Returns the comparator used to compare keys in this sorted map. - * - * @return the comparator or {@code null} if the natural order is used. - */ + /// Returns the comparator used to compare keys in this sorted map. + /// + /// #### Returns + /// + /// the comparator or `null` if the natural order is used. public Comparator comparator(); - /** - * Returns the first key in this sorted map. - * - * @return the first key in this sorted map. - * @throws NoSuchElementException - * if this sorted map is empty. - */ + /// Returns the first key in this sorted map. + /// + /// #### Returns + /// + /// the first key in this sorted map. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this sorted map is empty. public K firstKey(); - /** - * Returns a sorted map over a range of this sorted map with all keys that - * are less than the specified {@code endKey}. Changes to the returned - * sorted map are reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param endKey - * the high boundary of the range specified. - * @return a sorted map where the keys are less than {@code endKey}. - * @throws ClassCastException - * if the class of the end key is inappropriate for this sorted - * map. - * @throws NullPointerException - * if the end key is {@code null} and this sorted map does not - * support {@code null} keys. - * @throws IllegalArgumentException - * if this map is itself a sorted map over a range of another - * map and the specified key is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys that + /// are less than the specified `endKey`. Changes to the returned + /// sorted map are reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `endKey`: the high boundary of the range specified. + /// + /// #### Returns + /// + /// a sorted map where the keys are less than `endKey`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the end key is inappropriate for this sorted + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the end key is `null` and this sorted map does not + /// support `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if this map is itself a sorted map over a range of another + /// map and the specified key is outside of its range. public SortedMap headMap(K endKey); - /** - * Returns the last key in this sorted map. - * - * @return the last key in this sorted map. - * @throws NoSuchElementException - * if this sorted map is empty. - */ + /// Returns the last key in this sorted map. + /// + /// #### Returns + /// + /// the last key in this sorted map. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this sorted map is empty. public K lastKey(); - /** - * Returns a sorted map over a range of this sorted map with all keys - * greater than or equal to the specified {@code startKey} and less than the - * specified {@code endKey}. Changes to the returned sorted map are - * reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param startKey - * the low boundary of the range (inclusive). - * @param endKey - * the high boundary of the range (exclusive), - * @return a sorted map with the key from the specified range. - * @throws ClassCastException - * if the class of the start or end key is inappropriate for - * this sorted map. - * @throws NullPointerException - * if the start or end key is {@code null} and this sorted map - * does not support {@code null} keys. - * @throws IllegalArgumentException - * if the start key is greater than the end key, or if this map - * is itself a sorted map over a range of another sorted map and - * the specified range is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys + /// greater than or equal to the specified `startKey` and less than the + /// specified `endKey`. Changes to the returned sorted map are + /// reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `startKey`: the low boundary of the range (inclusive). + /// + /// - `endKey`: the high boundary of the range (exclusive), + /// + /// #### Returns + /// + /// a sorted map with the key from the specified range. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the start or end key is inappropriate for + /// this sorted map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the start or end key is `null` and this sorted map + /// does not support `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if the start key is greater than the end key, or if this map + /// is itself a sorted map over a range of another sorted map and + /// the specified range is outside of its range. public SortedMap subMap(K startKey, K endKey); - /** - * Returns a sorted map over a range of this sorted map with all keys that - * are greater than or equal to the specified {@code startKey}. Changes to - * the returned sorted map are reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param startKey - * the low boundary of the range specified. - * @return a sorted map where the keys are greater or equal to - * {@code startKey}. - * @throws ClassCastException - * if the class of the start key is inappropriate for this - * sorted map. - * @throws NullPointerException - * if the start key is {@code null} and this sorted map does not - * support {@code null} keys. - * @throws IllegalArgumentException - * if this map itself a sorted map over a range of another map - * and the specified key is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys that + /// are greater than or equal to the specified `startKey`. Changes to + /// the returned sorted map are reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `startKey`: the low boundary of the range specified. + /// + /// #### Returns + /// + /// @return a sorted map where the keys are greater or equal to + /// `startKey`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the class of the start key is inappropriate for this + /// sorted map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the start key is `null` and this sorted map does not + /// support `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if this map itself a sorted map over a range of another map + /// and the specified key is outside of its range. public SortedMap tailMap(K startKey); } diff --git a/Ports/CLDC11/src/java/util/SortedSet.java b/Ports/CLDC11/src/java/util/SortedSet.java index d387540b51..6f21ee11b5 100644 --- a/Ports/CLDC11/src/java/util/SortedSet.java +++ b/Ports/CLDC11/src/java/util/SortedSet.java @@ -18,102 +18,125 @@ package java.util; -/** - * SortedSet is a Set which iterates over its elements in a sorted order. The - * order is determined either by the elements natural ordering, or by a - * {@link Comparator} which is passed into a concrete implementation at - * construction time. All elements in this set must be mutually comparable. The - * ordering in this set must be consistent with {@code equals} of its elements. - * - * @see Comparator - * @see Comparable - */ +/// SortedSet is a Set which iterates over its elements in a sorted order. The +/// order is determined either by the elements natural ordering, or by a +/// `Comparator` which is passed into a concrete implementation at +/// construction time. All elements in this set must be mutually comparable. The +/// ordering in this set must be consistent with `equals` of its elements. +/// +/// #### See also +/// +/// - Comparator +/// +/// - Comparable public interface SortedSet extends Set { - /** - * Returns the comparator used to compare elements in this {@code SortedSet}. - * - * @return a comparator or null if the natural ordering is used. - */ + /// Returns the comparator used to compare elements in this `SortedSet`. + /// + /// #### Returns + /// + /// a comparator or null if the natural ordering is used. public Comparator comparator(); - /** - * Returns the first element in this {@code SortedSet}. The first element - * is the lowest element. - * - * @return the first element. - * @throws NoSuchElementException - * when this {@code SortedSet} is empty. - */ + /// Returns the first element in this `SortedSet`. The first element + /// is the lowest element. + /// + /// #### Returns + /// + /// the first element. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: when this `SortedSet` is empty. public E first(); - /** - * Returns a {@code SortedSet} of the specified portion of this - * {@code SortedSet} which contains elements less than the end element. The - * returned {@code SortedSet} is backed by this {@code SortedSet} so changes - * to one set are reflected by the other. - * - * @param end - * the end element. - * @return a subset where the elements are less than {@code end}. - * @throws ClassCastException - * when the class of the end element is inappropriate for this - * SubSet. - * @throws NullPointerException - * when the end element is null and this {@code SortedSet} does - * not support null elements. - */ + /// Returns a `SortedSet` of the specified portion of this + /// `SortedSet` which contains elements less than the end element. The + /// returned `SortedSet` is backed by this `SortedSet` so changes + /// to one set are reflected by the other. + /// + /// #### Parameters + /// + /// - `end`: the end element. + /// + /// #### Returns + /// + /// a subset where the elements are less than `end`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the class of the end element is inappropriate for this + /// SubSet. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the end element is null and this `SortedSet` does + /// not support null elements. public SortedSet headSet(E end); - /** - * Returns the last element in this {@code SortedSet}. The last element is - * the highest element. - * - * @return the last element. - * @throws NoSuchElementException - * when this {@code SortedSet} is empty. - */ + /// Returns the last element in this `SortedSet`. The last element is + /// the highest element. + /// + /// #### Returns + /// + /// the last element. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: when this `SortedSet` is empty. public E last(); - /** - * Returns a {@code SortedSet} of the specified portion of this - * {@code SortedSet} which contains elements greater or equal to the start - * element but less than the end element. The returned {@code SortedSet} is - * backed by this SortedMap so changes to one set are reflected by the - * other. - * - * @param start - * the start element. - * @param end - * the end element. - * @return a subset where the elements are greater or equal to {@code start} - * and less than {@code end}. - * @throws ClassCastException - * when the class of the start or end element is inappropriate - * for this SubSet. - * @throws NullPointerException - * when the start or end element is null and this - * {@code SortedSet} does not support null elements. - * @throws IllegalArgumentException - * when the start element is greater than the end element. - */ + /// Returns a `SortedSet` of the specified portion of this + /// `SortedSet` which contains elements greater or equal to the start + /// element but less than the end element. The returned `SortedSet` is + /// backed by this SortedMap so changes to one set are reflected by the + /// other. + /// + /// #### Parameters + /// + /// - `start`: the start element. + /// + /// - `end`: the end element. + /// + /// #### Returns + /// + /// @return a subset where the elements are greater or equal to `start` + /// and less than `end`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the class of the start or end element is inappropriate + /// for this SubSet. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the start or end element is null and this + /// `SortedSet` does not support null elements. + /// + /// - `IllegalArgumentException`: when the start element is greater than the end element. public SortedSet subSet(E start, E end); - /** - * Returns a {@code SortedSet} of the specified portion of this - * {@code SortedSet} which contains elements greater or equal to the start - * element. The returned {@code SortedSet} is backed by this - * {@code SortedSet} so changes to one set are reflected by the other. - * - * @param start - * the start element. - * @return a subset where the elements are greater or equal to {@code start} . - * @throws ClassCastException - * when the class of the start element is inappropriate for this - * SubSet. - * @throws NullPointerException - * when the start element is null and this {@code SortedSet} - * does not support null elements. - */ + /// Returns a `SortedSet` of the specified portion of this + /// `SortedSet` which contains elements greater or equal to the start + /// element. The returned `SortedSet` is backed by this + /// `SortedSet` so changes to one set are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the start element. + /// + /// #### Returns + /// + /// a subset where the elements are greater or equal to `start` . + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the class of the start element is inappropriate for this + /// SubSet. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the start element is null and this `SortedSet` + /// does not support null elements. public SortedSet tailSet(E start); } diff --git a/Ports/CLDC11/src/java/util/Stack.java b/Ports/CLDC11/src/java/util/Stack.java index e2b5aad53d..87036e616f 100644 --- a/Ports/CLDC11/src/java/util/Stack.java +++ b/Ports/CLDC11/src/java/util/Stack.java @@ -17,39 +17,40 @@ package java.util; -/** - * {@code Stack} is a Last-In/First-Out(LIFO) data structure which represents a - * stack of objects. It enables users to pop to and push from the stack, - * including null objects. There is no limit to the size of the stack. - */ +/// `Stack` is a Last-In/First-Out(LIFO) data structure which represents a +/// stack of objects. It enables users to pop to and push from the stack, +/// including null objects. There is no limit to the size of the stack. public class Stack extends Vector { private static final long serialVersionUID = 1224463164541339165L; - /** - * Constructs a stack with the default size of {@code Vector}. - */ + /// Constructs a stack with the default size of `Vector`. public Stack() { super(); } - /** - * Returns whether the stack is empty or not. - * - * @return {@code true} if the stack is empty, {@code false} otherwise. - */ + /// Returns whether the stack is empty or not. + /// + /// #### Returns + /// + /// `true` if the stack is empty, `false` otherwise. public boolean empty() { return isEmpty(); } - /** - * Returns the element at the top of the stack without removing it. - * - * @return the element at the top of the stack. - * @throws EmptyStackException - * if the stack is empty. - * @see #pop - */ + /// Returns the element at the top of the stack without removing it. + /// + /// #### Returns + /// + /// the element at the top of the stack. + /// + /// #### Throws + /// + /// - `EmptyStackException`: if the stack is empty. + /// + /// #### See also + /// + /// - #pop @SuppressWarnings("unchecked") public synchronized E peek() { try { @@ -59,15 +60,21 @@ public synchronized E peek() { } } - /** - * Returns the element at the top of the stack and removes it. - * - * @return the element at the top of the stack. - * @throws EmptyStackException - * if the stack is empty. - * @see #peek - * @see #push - */ + /// Returns the element at the top of the stack and removes it. + /// + /// #### Returns + /// + /// the element at the top of the stack. + /// + /// #### Throws + /// + /// - `EmptyStackException`: if the stack is empty. + /// + /// #### See also + /// + /// - #peek + /// + /// - #push @SuppressWarnings("unchecked") public synchronized E pop() { if (elementCount == 0) { @@ -80,29 +87,37 @@ public synchronized E pop() { return obj; } - /** - * Pushes the specified object onto the top of the stack. - * - * @param object - * The object to be added on top of the stack. - * @return the object argument. - * @see #peek - * @see #pop - */ + /// Pushes the specified object onto the top of the stack. + /// + /// #### Parameters + /// + /// - `object`: The object to be added on top of the stack. + /// + /// #### Returns + /// + /// the object argument. + /// + /// #### See also + /// + /// - #peek + /// + /// - #pop public E push(E object) { addElement(object); return object; } - /** - * Returns the index of the first occurrence of the object, starting from - * the top of the stack. - * - * @return the index of the first occurrence of the object, assuming that - * the topmost object on the stack has a distance of one. - * @param o - * the object to be searched. - */ + /// Returns the index of the first occurrence of the object, starting from + /// the top of the stack. + /// + /// #### Parameters + /// + /// - `o`: the object to be searched. + /// + /// #### Returns + /// + /// @return the index of the first occurrence of the object, assuming that + /// the topmost object on the stack has a distance of one. public synchronized int search(Object o) { final Object[] dumpArray = elementData; final int size = elementCount; diff --git a/Ports/CLDC11/src/java/util/StringTokenizer.java b/Ports/CLDC11/src/java/util/StringTokenizer.java index 18405801fe..324c279ae2 100644 --- a/Ports/CLDC11/src/java/util/StringTokenizer.java +++ b/Ports/CLDC11/src/java/util/StringTokenizer.java @@ -17,90 +17,80 @@ package java.util; -/** - * The {@code StringTokenizer} class allows an application to break a string - * into tokens by performing code point comparison. The {@code StringTokenizer} - * methods do not distinguish among identifiers, numbers, and quoted strings, - * nor do they recognize and skip comments. - *

- * The set of delimiters (the codepoints that separate tokens) may be specified - * either at creation time or on a per-token basis. - *

- * An instance of {@code StringTokenizer} behaves in one of three ways, - * depending on whether it was created with the {@code returnDelimiters} flag - * having the value {@code true} or {@code false}: - *

    - *
  • If returnDelims is {@code false}, delimiter code points serve to separate - * tokens. A token is a maximal sequence of consecutive code points that are not - * delimiters. - *
  • If returnDelims is {@code true}, delimiter code points are themselves - * considered to be tokens. In this case a token will be received for each - * delimiter code point. - *
- *

- * A token is thus either one delimiter code point, or a maximal sequence of - * consecutive code points that are not delimiters. - *

- * A {@code StringTokenizer} object internally maintains a current position - * within the string to be tokenized. Some operations advance this current - * position past the code point processed. - *

- * A token is returned by taking a substring of the string that was used to - * create the {@code StringTokenizer} object. - *

- * Here's an example of the use of the default delimiter {@code StringTokenizer} - * :

- * - * 
- * StringTokenizer st = new StringTokenizer("this is a test");
- * while (st.hasMoreTokens()) {
- *     println(st.nextToken());
- * }
- *
- * - *
- *

- * This prints the following output:

- * - * 
- *     this
- *     is
- *     a
- *     test
- *
- * - *
- *

- * Here's an example of how to use a {@code StringTokenizer} with a user - * specified delimiter:

- * - * 
- * StringTokenizer st = new StringTokenizer(
- *         "this is a test with supplementary characters \ud800\ud800\udc00\udc00",
- *         " \ud800\udc00");
- * while (st.hasMoreTokens()) {
- *     println(st.nextToken());
- * }
- *
- * - *
- *

- * This prints the following output:

- * - * 
- *     this
- *     is
- *     a
- *     test
- *     with
- *     supplementary
- *     characters
- *     \ud800
- *     \udc00
- *
- * - *
- */ +/// The `StringTokenizer` class allows an application to break a string +/// into tokens by performing code point comparison. The `StringTokenizer` +/// methods do not distinguish among identifiers, numbers, and quoted strings, +/// nor do they recognize and skip comments. +/// +/// The set of delimiters (the codepoints that separate tokens) may be specified +/// either at creation time or on a per-token basis. +/// +/// An instance of `StringTokenizer` behaves in one of three ways, +/// depending on whether it was created with the `returnDelimiters` flag +/// having the value `true` or `false`: +/// +/// - If returnDelims is `false`, delimiter code points serve to separate +/// tokens. A token is a maximal sequence of consecutive code points that are not +/// delimiters. +/// +/// - If returnDelims is `true`, delimiter code points are themselves +/// considered to be tokens. In this case a token will be received for each +/// delimiter code point. +/// +/// A token is thus either one delimiter code point, or a maximal sequence of +/// consecutive code points that are not delimiters. +/// +/// A `StringTokenizer` object internally maintains a current position +/// within the string to be tokenized. Some operations advance this current +/// position past the code point processed. +/// +/// A token is returned by taking a substring of the string that was used to +/// create the `StringTokenizer` object. +/// +/// Here's an example of the use of the default delimiter `StringTokenizer` +/// : +/// +/// ```java +/// StringTokenizer st = new StringTokenizer("this is a test"); +/// while (st.hasMoreTokens()) { +/// println(st.nextToken()); +/// } +/// ``` +/// +/// This prints the following output: +/// +/// ```java +/// this +/// is +/// a +/// test +/// ``` +/// +/// Here's an example of how to use a `StringTokenizer` with a user +/// specified delimiter: +/// +/// ```java +/// StringTokenizer st = new StringTokenizer( +/// "this is a test with supplementary characters \ud800\ud800\udc00\udc00", +/// " \ud800\udc00"); +/// while (st.hasMoreTokens()) { +/// println(st.nextToken()); +/// } +/// ``` +/// +/// This prints the following output: +/// +/// ```java +/// this +/// is +/// a +/// test +/// with +/// supplementary +/// characters +/// \ud800 +/// \udc00 +/// ``` public class StringTokenizer implements java.util.Enumeration { private String string; @@ -111,48 +101,45 @@ public class StringTokenizer implements java.util.Enumeration { private int position; - /** - * Constructs a new {@code StringTokenizer} for the parameter string using - * whitespace as the delimiter. The {@code returnDelimiters} flag is set to - * {@code false}. - * - * @param string - * the string to be tokenized. - */ + /// Constructs a new `StringTokenizer` for the parameter string using + /// whitespace as the delimiter. The `returnDelimiters` flag is set to + /// `false`. + /// + /// #### Parameters + /// + /// - `string`: the string to be tokenized. public StringTokenizer(String string) { this(string, " \t\n\r\f", false); //$NON-NLS-1$ } - /** - * Constructs a new {@code StringTokenizer} for the parameter string using - * the specified delimiters. The {@code returnDelimiters} flag is set to - * {@code false}. If {@code delimiters} is {@code null}, this constructor - * doesn't throw an {@code Exception}, but later calls to some methods might - * throw a {@code NullPointerException}. - * - * @param string - * the string to be tokenized. - * @param delimiters - * the delimiters to use. - */ + /// Constructs a new `StringTokenizer` for the parameter string using + /// the specified delimiters. The `returnDelimiters` flag is set to + /// `false`. If `delimiters` is `null`, this constructor + /// doesn't throw an `Exception`, but later calls to some methods might + /// throw a `NullPointerException`. + /// + /// #### Parameters + /// + /// - `string`: the string to be tokenized. + /// + /// - `delimiters`: the delimiters to use. public StringTokenizer(String string, String delimiters) { this(string, delimiters, false); } - /** - * Constructs a new {@code StringTokenizer} for the parameter string using - * the specified delimiters, returning the delimiters as tokens if the - * parameter {@code returnDelimiters} is {@code true}. If {@code delimiters} - * is null this constructor doesn't throw an {@code Exception}, but later - * calls to some methods might throw a {@code NullPointerException}. - * - * @param string - * the string to be tokenized. - * @param delimiters - * the delimiters to use. - * @param returnDelimiters - * {@code true} to return each delimiter as a token. - */ + /// Constructs a new `StringTokenizer` for the parameter string using + /// the specified delimiters, returning the delimiters as tokens if the + /// parameter `returnDelimiters` is `true`. If `delimiters` + /// is null this constructor doesn't throw an `Exception`, but later + /// calls to some methods might throw a `NullPointerException`. + /// + /// #### Parameters + /// + /// - `string`: the string to be tokenized. + /// + /// - `delimiters`: the delimiters to use. + /// + /// - `returnDelimiters`: `true` to return each delimiter as a token. public StringTokenizer(String string, String delimiters, boolean returnDelimiters) { if (string != null) { @@ -164,12 +151,11 @@ public StringTokenizer(String string, String delimiters, throw new NullPointerException(); } - /** - * Returns the number of unprocessed tokens remaining in the string. - * - * @return number of tokens that can be retreived before an {@code - * Exception} will result from a call to {@code nextToken()}. - */ + /// Returns the number of unprocessed tokens remaining in the string. + /// + /// #### Returns + /// + /// number of tokens that can be retreived before an `Exception` will result from a call to `nextToken()`. public int countTokens() { int count = 0; boolean inToken = false; @@ -190,21 +176,21 @@ public int countTokens() { return count; } - /** - * Returns {@code true} if unprocessed tokens remain. This method is - * implemented in order to satisfy the {@code Enumeration} interface. - * - * @return {@code true} if unprocessed tokens remain. - */ + /// Returns `true` if unprocessed tokens remain. This method is + /// implemented in order to satisfy the `Enumeration` interface. + /// + /// #### Returns + /// + /// `true` if unprocessed tokens remain. public boolean hasMoreElements() { return hasMoreTokens(); } - /** - * Returns {@code true} if unprocessed tokens remain. - * - * @return {@code true} if unprocessed tokens remain. - */ + /// Returns `true` if unprocessed tokens remain. + /// + /// #### Returns + /// + /// `true` if unprocessed tokens remain. public boolean hasMoreTokens() { if (delimiters == null) { throw new NullPointerException(); @@ -223,25 +209,29 @@ public boolean hasMoreTokens() { return false; } - /** - * Returns the next token in the string as an {@code Object}. This method is - * implemented in order to satisfy the {@code Enumeration} interface. - * - * @return next token in the string as an {@code Object} - * @throws NoSuchElementException - * if no tokens remain. - */ + /// Returns the next token in the string as an `Object`. This method is + /// implemented in order to satisfy the `Enumeration` interface. + /// + /// #### Returns + /// + /// next token in the string as an `Object` + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if no tokens remain. public Object nextElement() { return nextToken(); } - /** - * Returns the next token in the string as a {@code String}. - * - * @return next token in the string as a {@code String}. - * @throws NoSuchElementException - * if no tokens remain. - */ + /// Returns the next token in the string as a `String`. + /// + /// #### Returns + /// + /// next token in the string as a `String`. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if no tokens remain. public String nextToken() { if (delimiters == null) { throw new NullPointerException(); @@ -272,16 +262,20 @@ public String nextToken() { throw new NoSuchElementException(); } - /** - * Returns the next token in the string as a {@code String}. The delimiters - * used are changed to the specified delimiters. - * - * @param delims - * the new delimiters to use. - * @return next token in the string as a {@code String}. - * @throws NoSuchElementException - * if no tokens remain. - */ + /// Returns the next token in the string as a `String`. The delimiters + /// used are changed to the specified delimiters. + /// + /// #### Parameters + /// + /// - `delims`: the new delimiters to use. + /// + /// #### Returns + /// + /// next token in the string as a `String`. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if no tokens remain. public String nextToken(String delims) { this.delimiters = delims; return nextToken(); diff --git a/Ports/CLDC11/src/java/util/TimeZone.java b/Ports/CLDC11/src/java/util/TimeZone.java index 7fda3adcbe..77f5094938 100644 --- a/Ports/CLDC11/src/java/util/TimeZone.java +++ b/Ports/CLDC11/src/java/util/TimeZone.java @@ -22,30 +22,24 @@ * have any questions. */ package java.util; -/** - * TimeZone represents a time zone offset, and also figures out daylight savings. - * Typically, you get a TimeZone using getDefault which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, getDefault creates a TimeZone object based on Japanese Standard Time. - * You can also get a TimeZone using getTimeZone along with a time zone ID. For instance, the time zone ID for the Pacific Standard Time zone is "PST". So, you can get a PST TimeZone object with: - * This class is a pure subset of the java.util.TimeZone class in JDK 1.3. - * The only time zone ID that is required to be supported is "GMT". - * Apart from the methods and variables being subset, the semantics of the getTimeZone() method may also be subset: custom IDs such as "GMT-8:00" are not required to be supported. - * Version: CLDC 1.1 02/01/2002 (Based on JDK 1.3) See Also:Calendar, Date - */ +/// TimeZone represents a time zone offset, and also figures out daylight savings. +/// Typically, you get a TimeZone using getDefault which creates a TimeZone based on the time zone where the program is running. For example, for a program running in Japan, getDefault creates a TimeZone object based on Japanese Standard Time. +/// You can also get a TimeZone using getTimeZone along with a time zone ID. For instance, the time zone ID for the Pacific Standard Time zone is "PST". So, you can get a PST TimeZone object with: +/// This class is a pure subset of the java.util.TimeZone class in JDK 1.3. +/// The only time zone ID that is required to be supported is "GMT". +/// Apart from the methods and variables being subset, the semantics of the getTimeZone() method may also be subset: custom IDs such as "GMT-8:00" are not required to be supported. +/// Version: CLDC 1.1 02/01/2002 (Based on JDK 1.3) See Also:Calendar, Date public abstract class TimeZone{ public TimeZone(){ //TODO codavaj!! } - /** - * Gets all the available IDs supported. - */ + /// Gets all the available IDs supported. public static java.lang.String[] getAvailableIDs(){ return null; //TODO codavaj!! } - /** - * Gets the default TimeZone for this host. The source of the default TimeZone may vary with implementation. - */ + /// Gets the default TimeZone for this host. The source of the default TimeZone may vary with implementation. public static java.util.TimeZone getDefault(){ return null; //TODO codavaj!! } @@ -53,33 +47,23 @@ public static java.util.TimeZone getDefault(){ public static void setDefault(TimeZone timezone) { } - /** - * Gets the ID of this time zone. - */ + /// Gets the ID of this time zone. public java.lang.String getID(){ return null; //TODO codavaj!! } - /** - * Gets offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Assume that the start and end month are distinct. This method may return incorrect results for rules that start at the end of February (e.g., last Sunday in February) or the beginning of March (e.g., March 1). - */ + /// Gets offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Gets the time zone offset, for current date, modified in case of daylight savings. This is the offset to add *to* GMT to get local time. Assume that the start and end month are distinct. This method may return incorrect results for rules that start at the end of February (e.g., last Sunday in February) or the beginning of March (e.g., March 1). public abstract int getOffset(int era, int year, int month, int day, int dayOfWeek, int millis); - /** - * Gets the GMT offset for this time zone. - */ + /// Gets the GMT offset for this time zone. public abstract int getRawOffset(); - /** - * Gets the TimeZone for the given ID. - */ + /// Gets the TimeZone for the given ID. public static java.util.TimeZone getTimeZone(java.lang.String ID){ return null; //TODO codavaj!! } - /** - * Queries if this time zone uses Daylight Savings Time. - */ + /// Queries if this time zone uses Daylight Savings Time. public abstract boolean useDaylightTime(); } diff --git a/Ports/CLDC11/src/java/util/TreeMap.java b/Ports/CLDC11/src/java/util/TreeMap.java index 783f004c07..1952168039 100644 --- a/Ports/CLDC11/src/java/util/TreeMap.java +++ b/Ports/CLDC11/src/java/util/TreeMap.java @@ -17,18 +17,18 @@ package java.util; -/** - * TreeMap is an implementation of SortedMap. All optional operations (adding - * and removing) are supported. The values can be any objects. The keys can be - * any objects which are comparable to each other either using their natural - * - * @param - * type of key - * @param - * type of value - * - * @since 1.2 - */ +/// TreeMap is an implementation of SortedMap. All optional operations (adding +/// and removing) are supported. The values can be any objects. The keys can be +/// any objects which are comparable to each other either using their natural +/// +/// @param +/// type of key +/// @param +/// type of value +/// +/// #### Since +/// +/// 1.2 public class TreeMap extends AbstractMap implements NavigableMap { private static final long serialVersionUID = 919286545866124006L; @@ -73,12 +73,10 @@ public Node() { } } - /** - * Entry is an internal class which is used to hold the entries of a - * TreeMap. - * - * also used to record key, value, and position - */ + /// Entry is an internal class which is used to hold the entries of a + /// TreeMap. + /// + /// also used to record key, value, and position static class Entry extends MapEntry { Entry parent, left, right; @@ -2561,11 +2559,13 @@ public abstract NavigableMap subMap(K start, public abstract NavigableMap tailMap(K start, boolean inclusive); - /** - * - * @param key - * @return false if the key bigger than the end key (if any) - */ + /// #### Parameters + /// + /// - `key` + /// + /// #### Returns + /// + /// false if the key bigger than the end key (if any) final boolean checkUpperBound(K key) { if (toEnd) { int result = (null != comparator()) ? comparator().compare(key, hi) @@ -2575,11 +2575,13 @@ final boolean checkUpperBound(K key) { return true; } - /** - * - * @param key - * @return false if the key smaller than the start key (if any) - */ + /// #### Parameters + /// + /// - `key` + /// + /// #### Returns + /// + /// false if the key smaller than the start key (if any) final boolean checkLowerBound(K key) { if (fromStart) { int result = - ((null != comparator()) ? comparator().compare(lo,key) @@ -3675,47 +3677,45 @@ NavigableSubMap descendingSubMap() { } } - /** - * Constructs a new empty {@code TreeMap} instance. - */ + /// Constructs a new empty `TreeMap` instance. public TreeMap() { super(); } - /** - * Constructs a new empty {@code TreeMap} instance with the specified - * comparator. - * - * @param comparator - * the comparator to compare keys with. - */ + /// Constructs a new empty `TreeMap` instance with the specified + /// comparator. + /// + /// #### Parameters + /// + /// - `comparator`: the comparator to compare keys with. public TreeMap(Comparator comparator) { this.comparator = comparator; } - /** - * Constructs a new {@code TreeMap} instance containing the mappings from - * the specified map and using natural ordering. - * - * @param map - * the mappings to add. - * @throws ClassCastException - * if a key in the specified map does not implement the - * Comparable interface, or if the keys in the map cannot be - * compared. - */ + /// Constructs a new `TreeMap` instance containing the mappings from + /// the specified map and using natural ordering. + /// + /// #### Parameters + /// + /// - `map`: the mappings to add. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if a key in the specified map does not implement the + /// Comparable interface, or if the keys in the map cannot be + /// compared. public TreeMap(Map map) { this(); putAll(map); } - /** - * Constructs a new {@code TreeMap} instance containing the mappings from - * the specified SortedMap and using the same comparator. - * - * @param map - * the mappings to add. - */ + /// Constructs a new `TreeMap` instance containing the mappings from + /// the specified SortedMap and using the same comparator. + /// + /// #### Parameters + /// + /// - `map`: the mappings to add. public TreeMap(SortedMap map) { this(map.comparator()); Node lastNode = null; @@ -3744,12 +3744,13 @@ Node addToLast(Node last, K key, V value) { return last; } - /** - * Removes all mappings from this TreeMap, leaving it empty. - * - * @see Map#isEmpty() - * @see #size() - */ + /// Removes all mappings from this TreeMap, leaving it empty. + /// + /// #### See also + /// + /// - Map#isEmpty() + /// + /// - #size() @Override public void clear() { root = null; @@ -3757,29 +3758,35 @@ public void clear() { modCount++; } - /** - * Returns the comparator used to compare elements in this map. - * - * @return the comparator or {@code null} if the natural ordering is used. - */ + /// Returns the comparator used to compare elements in this map. + /// + /// #### Returns + /// + /// the comparator or `null` if the natural ordering is used. public Comparator comparator() { return comparator; } - /** - * Returns whether this map contains the specified key. - * - * @param key - * the key to search for. - * @return {@code true} if this map contains the specified key, - * {@code false} otherwise. - * @throws ClassCastException - * if the specified key cannot be compared with the keys in this - * map. - * @throws NullPointerException - * if the specified key is {@code null} and the comparator - * cannot handle {@code null} keys. - */ + /// Returns whether this map contains the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified key, + /// `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the specified key cannot be compared with the keys in this + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the specified key is `null` and the comparator + /// cannot handle `null` keys. @SuppressWarnings("unchecked") @Override public boolean containsKey(Object key) { @@ -3825,14 +3832,16 @@ public boolean containsKey(Object key) { return false; } - /** - * Returns whether this map contains the specified value. - * - * @param value - * the value to search for. - * @return {@code true} if this map contains the specified value, - * {@code false} otherwise. - */ + /// Returns whether this map contains the specified value. + /// + /// #### Parameters + /// + /// - `value`: the value to search for. + /// + /// #### Returns + /// + /// @return `true` if this map contains the specified value, + /// `false` otherwise. @Override public boolean containsValue(Object value) { if (root == null) { @@ -4197,13 +4206,15 @@ && cmp(object,keyK, foundNode.keys[foundIndex]) >= 0) { return null; } - /** - * Returns the first key in this map. - * - * @return the first key in this map. - * @throws NoSuchElementException - * if this map is empty. - */ + /// Returns the first key in this map. + /// + /// #### Returns + /// + /// the first key in this map. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this map is empty. public K firstKey() { if (root != null) { Node node = minimum(root); @@ -4240,18 +4251,23 @@ Node findNode(K key) { return null; } - /** - * Returns the value of the mapping with the specified key. - * - * @param key - * the key. - * @return the value of the mapping with the specified key. - * @throws ClassCastException - * if the key cannot be compared with the keys in this map. - * @throws NullPointerException - * if the key is {@code null} and the comparator cannot handle - * {@code null}. - */ + /// Returns the value of the mapping with the specified key. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// #### Returns + /// + /// the value of the mapping with the specified key. + /// + /// #### Throws + /// + /// - `ClassCastException`: if the key cannot be compared with the keys in this map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the key is `null` and the comparator cannot handle + /// `null`. @SuppressWarnings("unchecked") @Override public V get(Object key) { @@ -4296,13 +4312,13 @@ public V get(Object key) { return null; } - /** - * Returns a set of the keys contained in this map. The set is backed by - * this map so changes to one are reflected by the other. The set does not - * support adding. - * - * @return a set of the keys. - */ + /// Returns a set of the keys contained in this map. The set is backed by + /// this map so changes to one are reflected by the other. The set does not + /// support adding. + /// + /// #### Returns + /// + /// a set of the keys. @Override public Set keySet() { if (keySet == null) { @@ -4331,13 +4347,15 @@ public Iterator iterator() { return keySet; } - /** - * Returns the last key in this map. - * - * @return the last key in this map. - * @throws NoSuchElementException - * if this map is empty. - */ + /// Returns the last key in this map. + /// + /// #### Returns + /// + /// the last key in this map. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this map is empty. public K lastKey() { if (root != null) { Node node = maximum(root); @@ -4389,22 +4407,28 @@ private int cmp(java.lang.Comparable object, K key1, K key2) { key1, key2); } - /** - * Maps the specified key to the specified value. - * - * @param key - * the key. - * @param value - * the value. - * @return the value of any previous mapping with the specified key or - * {@code null} if there was no mapping. - * @throws ClassCastException - * if the specified key cannot be compared with the keys in this - * map. - * @throws NullPointerException - * if the specified key is {@code null} and the comparator - * cannot handle {@code null} keys. - */ + /// Maps the specified key to the specified value. + /// + /// #### Parameters + /// + /// - `key`: the key. + /// + /// - `value`: the value. + /// + /// #### Returns + /// + /// @return the value of any previous mapping with the specified key or + /// `null` if there was no mapping. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the specified key cannot be compared with the keys in this + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the specified key is `null` and the comparator + /// cannot handle `null` keys. @Override public V put(K key, V value) { return putImpl(key, value); @@ -4776,20 +4800,23 @@ private void leftRotate(Node x) { x.parent = y; } - /** - * Copies all the mappings in the given map to this map. These mappings will - * replace all mappings that this map had for any of the keys currently in - * the given map. - * - * @param map - * the map to copy mappings from. - * @throws ClassCastException - * if a key in the specified map cannot be compared with the - * keys in this map. - * @throws NullPointerException - * if a key in the specified map is {@code null} and the - * comparator cannot handle {@code null} keys. - */ + /// Copies all the mappings in the given map to this map. These mappings will + /// replace all mappings that this map had for any of the keys currently in + /// the given map. + /// + /// #### Parameters + /// + /// - `map`: the map to copy mappings from. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if a key in the specified map cannot be compared with the + /// keys in this map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if a key in the specified map is `null` and the + /// comparator cannot handle `null` keys. @Override public void putAll(Map map) { Iterator it = map.entrySet().iterator(); @@ -4799,20 +4826,26 @@ public void putAll(Map map) { } } - /** - * Removes the mapping with the specified key from this map. - * - * @param key - * the key of the mapping to remove. - * @return the value of the removed mapping or {@code null} if no mapping - * for the specified key was found. - * @throws ClassCastException - * if the specified key cannot be compared with the keys in this - * map. - * @throws NullPointerException - * if the specified key is {@code null} and the comparator - * cannot handle {@code null} keys. - */ + /// Removes the mapping with the specified key from this map. + /// + /// #### Parameters + /// + /// - `key`: the key of the mapping to remove. + /// + /// #### Returns + /// + /// @return the value of the removed mapping or `null` if no mapping + /// for the specified key was found. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the specified key cannot be compared with the keys in this + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the specified key is `null` and the comparator + /// cannot handle `null` keys. @SuppressWarnings("unchecked") @Override public V remove(Object key) { @@ -5192,35 +5225,35 @@ private void fixup(Node x) { x.color = false; } - /** - * Returns the number of mappings in this map. - * - * @return the number of mappings in this map. - */ + /// Returns the number of mappings in this map. + /// + /// #### Returns + /// + /// the number of mappings in this map. @Override public int size() { return size; } - /** - * Returns a collection of the values contained in this map. The collection - * is backed by this map so changes to one are reflected by the other. The - * collection supports remove, removeAll, retainAll and clear operations, - * and it does not support add or addAll operations. - *

- * This method returns a collection which is the subclass of - * AbstractCollection. The iterator method of this subclass returns a - * "wrapper object" over the iterator of map's entrySet(). The {@code size} - * method wraps the map's size method and the {@code contains} method wraps - * the map's containsValue method. - *

- * The collection is created when this method is called for the first time - * and returned in response to all subsequent calls. This method may return - * different collections when multiple concurrent calls occur, since no - * synchronization is performed. - * - * @return a collection of the values contained in this map. - */ + /// Returns a collection of the values contained in this map. The collection + /// is backed by this map so changes to one are reflected by the other. The + /// collection supports remove, removeAll, retainAll and clear operations, + /// and it does not support add or addAll operations. + /// + /// This method returns a collection which is the subclass of + /// AbstractCollection. The iterator method of this subclass returns a + /// "wrapper object" over the iterator of map's entrySet(). The `size` + /// method wraps the map's size method and the `contains` method wraps + /// the map's containsValue method. + /// + /// The collection is created when this method is called for the first time + /// and returned in response to all subsequent calls. This method may return + /// different collections when multiple concurrent calls occur, since no + /// synchronization is performed. + /// + /// #### Returns + /// + /// a collection of the values contained in this map. @Override public Collection values() { if (valuesCollection == null) { @@ -5249,32 +5282,41 @@ public Iterator iterator() { return valuesCollection; } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#firstEntry() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#firstEntry() public Map.Entry firstEntry() { return newImmutableEntry(findSmallestEntry()); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#lastEntry() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#lastEntry() public Map.Entry lastEntry() { return newImmutableEntry(findBiggestEntry()); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#pollFirstEntry() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#pollFirstEntry() public Map.Entry pollFirstEntry() { Entry node = findSmallestEntry(); SimpleImmutableEntry result = newImmutableEntry(node); @@ -5284,12 +5326,15 @@ public Map.Entry pollFirstEntry() { return result; } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#pollLastEntry() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#pollLastEntry() public Map.Entry pollLastEntry() { Entry node = findBiggestEntry(); SimpleImmutableEntry result = newImmutableEntry(node); @@ -5299,85 +5344,109 @@ public Map.Entry pollLastEntry() { return result; } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#higherEntry(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#higherEntry(Object) public Map.Entry higherEntry(K key) { return newImmutableEntry(findHigherEntry(key)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#higherKey(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#higherKey(Object) public K higherKey(K key) { Map.Entry entry = higherEntry(key); return (null == entry) ? null : entry.getKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#lowerEntry(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#lowerEntry(Object) public Map.Entry lowerEntry(K key) { return newImmutableEntry(findLowerEntry(key)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#lowerKey(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#lowerKey(Object) public K lowerKey(K key) { Map.Entry entry = lowerEntry(key); return (null == entry) ? null : entry.getKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#ceilingEntry(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#ceilingEntry(java.lang.Object) public Map.Entry ceilingEntry(K key) { return newImmutableEntry(findCeilingEntry(key)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#ceilingKey(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#ceilingKey(java.lang.Object) public K ceilingKey(K key) { Map.Entry entry = ceilingEntry(key); return (null == entry) ? null : entry.getKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#floorEntry(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#floorEntry(Object) public Map.Entry floorEntry(K key) { return newImmutableEntry(findFloorEntry(key)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#floorKey(Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#floorKey(Object) public K floorKey(K key) { Map.Entry entry = floorEntry(key); return (null == entry) ? null : entry.getKey(); @@ -5421,14 +5490,14 @@ static Node maximum(Node x) { return x; } - /** - * Returns a set containing all of the mappings in this map. Each mapping is - * an instance of {@link Map.Entry}. As the set is backed by this map, - * changes in one will be reflected in the other. It does not support adding - * operations. - * - * @return a set of the mappings. - */ + /// Returns a set containing all of the mappings in this map. Each mapping is + /// an instance of `Map.Entry`. As the set is backed by this map, + /// changes in one will be reflected in the other. It does not support adding + /// operations. + /// + /// #### Returns + /// + /// a set of the mappings. @Override public Set> entrySet() { if (entrySet == null) { @@ -5464,12 +5533,15 @@ public Iterator> iterator() { return entrySet; } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#navigableKeySet() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#navigableKeySet() @SuppressWarnings("unchecked") public NavigableSet navigableKeySet() { return (null != navigableKeySet) ? navigableKeySet @@ -5477,33 +5549,42 @@ public NavigableSet navigableKeySet() { .navigableKeySet()); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#descendingKeySet() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#descendingKeySet() public NavigableSet descendingKeySet() { return descendingMap().navigableKeySet(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#descendingMap() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#descendingMap() public NavigableMap descendingMap() { return (null != descendingMap) ? descendingMap : (descendingMap = new DescendingSubMap(this)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#subMap(Object, boolean, Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#subMap(Object, boolean, Object, boolean) public NavigableMap subMap(K start, boolean startInclusive, K end, boolean endInclusive) { if (keyCompare(start, end) <= 0) { @@ -5513,55 +5594,68 @@ public NavigableMap subMap(K start, boolean startInclusive, K end, throw new IllegalArgumentException(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#headMap(Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#headMap(Object, boolean) public NavigableMap headMap(K end, boolean inclusive) { // check for error keyCompare(end, end); return new AscendingSubMap(this, end, inclusive); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableMap#tailMap(Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableMap#tailMap(Object, boolean) public NavigableMap tailMap(K start, boolean inclusive) { // check for error keyCompare(start, start); return new AscendingSubMap(start, inclusive, this); } - /** - * Returns a sorted map over a range of this sorted map with all keys - * greater than or equal to the specified {@code startKey} and less than the - * specified {@code endKey}. Changes to the returned sorted map are - * reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param startKey - * the low boundary of the range (inclusive). - * @param endKey - * the high boundary of the range (exclusive), - * @return a sorted map with the key from the specified range. - * @throws ClassCastException - * if the start or end key cannot be compared with the keys in - * this map. - * @throws NullPointerException - * if the start or end key is {@code null} and the comparator - * cannot handle {@code null} keys. - * @throws IllegalArgumentException - * if the start key is greater than the end key, or if this map - * is itself a sorted map over a range of another sorted map and - * the specified range is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys + /// greater than or equal to the specified `startKey` and less than the + /// specified `endKey`. Changes to the returned sorted map are + /// reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `startKey`: the low boundary of the range (inclusive). + /// + /// - `endKey`: the high boundary of the range (exclusive), + /// + /// #### Returns + /// + /// a sorted map with the key from the specified range. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the start or end key cannot be compared with the keys in + /// this map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the start or end key is `null` and the comparator + /// cannot handle `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if the start key is greater than the end key, or if this map + /// is itself a sorted map over a range of another sorted map and + /// the specified range is outside of its range. public SortedMap subMap(K startKey, K endKey) { if (comparator == null) { if (toComparable(startKey).compareTo(endKey) <= 0) { @@ -5575,53 +5669,67 @@ public SortedMap subMap(K startKey, K endKey) { throw new IllegalArgumentException(); } - /** - * Returns a sorted map over a range of this sorted map with all keys that - * are less than the specified {@code endKey}. Changes to the returned - * sorted map are reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param endKey - * the high boundary of the range specified. - * @return a sorted map where the keys are less than {@code endKey}. - * @throws ClassCastException - * if the specified key cannot be compared with the keys in this - * map. - * @throws NullPointerException - * if the specified key is {@code null} and the comparator - * cannot handle {@code null} keys. - * @throws IllegalArgumentException - * if this map is itself a sorted map over a range of another - * map and the specified key is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys that + /// are less than the specified `endKey`. Changes to the returned + /// sorted map are reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `endKey`: the high boundary of the range specified. + /// + /// #### Returns + /// + /// a sorted map where the keys are less than `endKey`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the specified key cannot be compared with the keys in this + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the specified key is `null` and the comparator + /// cannot handle `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if this map is itself a sorted map over a range of another + /// map and the specified key is outside of its range. public SortedMap headMap(K endKey) { return headMap(endKey, false); } - /** - * Returns a sorted map over a range of this sorted map with all keys that - * are greater than or equal to the specified {@code startKey}. Changes to - * the returned sorted map are reflected in this sorted map and vice versa. - *

- * Note: The returned map will not allow an insertion of a key outside the - * specified range. - * - * @param startKey - * the low boundary of the range specified. - * @return a sorted map where the keys are greater or equal to - * {@code startKey}. - * @throws ClassCastException - * if the specified key cannot be compared with the keys in this - * map. - * @throws NullPointerException - * if the specified key is {@code null} and the comparator - * cannot handle {@code null} keys. - * @throws IllegalArgumentException - * if this map itself a sorted map over a range of another map - * and the specified key is outside of its range. - */ + /// Returns a sorted map over a range of this sorted map with all keys that + /// are greater than or equal to the specified `startKey`. Changes to + /// the returned sorted map are reflected in this sorted map and vice versa. + /// + /// Note: The returned map will not allow an insertion of a key outside the + /// specified range. + /// + /// #### Parameters + /// + /// - `startKey`: the low boundary of the range specified. + /// + /// #### Returns + /// + /// @return a sorted map where the keys are greater or equal to + /// `startKey`. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// if the specified key cannot be compared with the keys in this + /// map. + /// + /// - `NullPointerException`: @throws NullPointerException + /// if the specified key is `null` and the comparator + /// cannot handle `null` keys. + /// + /// - `IllegalArgumentException`: @throws IllegalArgumentException + /// if this map itself a sorted map over a range of another map + /// and the specified key is outside of its range. public SortedMap tailMap(K startKey) { return tailMap(startKey, true); } diff --git a/Ports/CLDC11/src/java/util/TreeSet.java b/Ports/CLDC11/src/java/util/TreeSet.java index 5db3434de3..7c2303723d 100644 --- a/Ports/CLDC11/src/java/util/TreeSet.java +++ b/Ports/CLDC11/src/java/util/TreeSet.java @@ -17,17 +17,17 @@ package java.util; -/** - * TreeSet is an implementation of SortedSet. All optional operations (adding - * and removing) are supported. The elements can be any objects which are - * comparable to each other either using their natural order or a specified - * Comparator. - * - * @since 1.2 - */ +/// TreeSet is an implementation of SortedSet. All optional operations (adding +/// and removing) are supported. The elements can be any objects which are +/// comparable to each other either using their natural order or a specified +/// Comparator. +/// +/// #### Since +/// +/// 1.2 public class TreeSet extends AbstractSet implements NavigableSet { - /** Keys are this set's elements. Values are always Boolean.TRUE */ + /// Keys are this set's elements. Values are always Boolean.TRUE private transient NavigableMap backingMap; private transient NavigableSet descendingSet; @@ -36,48 +36,46 @@ public class TreeSet extends AbstractSet implements NavigableSet { backingMap = map; } - /** - * Constructs a new empty instance of {@code TreeSet} which uses natural - * ordering. - */ + /// Constructs a new empty instance of `TreeSet` which uses natural + /// ordering. public TreeSet() { backingMap = new TreeMap(); } - /** - * Constructs a new instance of {@code TreeSet} which uses natural ordering - * and containing the unique elements in the specified collection. - * - * @param collection - * the collection of elements to add. - * @throws ClassCastException - * when an element in the collection does not implement the - * Comparable interface, or the elements in the collection - * cannot be compared. - */ + /// Constructs a new instance of `TreeSet` which uses natural ordering + /// and containing the unique elements in the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an element in the collection does not implement the + /// Comparable interface, or the elements in the collection + /// cannot be compared. public TreeSet(Collection collection) { this(); addAll(collection); } - /** - * Constructs a new empty instance of {@code TreeSet} which uses the - * specified comparator. - * - * @param comparator - * the comparator to use. - */ + /// Constructs a new empty instance of `TreeSet` which uses the + /// specified comparator. + /// + /// #### Parameters + /// + /// - `comparator`: the comparator to use. public TreeSet(Comparator comparator) { backingMap = new TreeMap(comparator); } - /** - * Constructs a new instance of {@code TreeSet} containing the elements of - * the specified SortedSet and using the same Comparator. - * - * @param set - * the SortedSet of elements to add. - */ + /// Constructs a new instance of `TreeSet` containing the elements of + /// the specified SortedSet and using the same Comparator. + /// + /// #### Parameters + /// + /// - `set`: the SortedSet of elements to add. public TreeSet(SortedSet set) { this(set.comparator()); Iterator it = set.iterator(); @@ -86,247 +84,307 @@ public TreeSet(SortedSet set) { } } - /** - * Adds the specified object to this {@code TreeSet}. - * - * @param object - * the object to add. - * @return {@code true} when this {@code TreeSet} did not already contain - * the object, {@code false} otherwise. - * @throws ClassCastException - * when the object cannot be compared with the elements in this - * {@code TreeSet}. - * @throws NullPointerException - * when the object is null and the comparator cannot handle - * null. - */ + /// Adds the specified object to this `TreeSet`. + /// + /// #### Parameters + /// + /// - `object`: the object to add. + /// + /// #### Returns + /// + /// @return `true` when this `TreeSet` did not already contain + /// the object, `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the object cannot be compared with the elements in this + /// `TreeSet`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the object is null and the comparator cannot handle + /// null. @Override public boolean add(E object) { return backingMap.put(object, Boolean.TRUE) == null; } - /** - * Adds the objects in the specified collection to this {@code TreeSet}. - * - * @param collection - * the collection of objects to add. - * @return {@code true} if this {@code TreeSet} was modified, {@code false} - * otherwise. - * @throws ClassCastException - * when an object in the collection cannot be compared with the - * elements in this {@code TreeSet}. - * @throws NullPointerException - * when an object in the collection is null and the comparator - * cannot handle null. - */ + /// Adds the objects in the specified collection to this `TreeSet`. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to add. + /// + /// #### Returns + /// + /// @return `true` if this `TreeSet` was modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when an object in the collection cannot be compared with the + /// elements in this `TreeSet`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when an object in the collection is null and the comparator + /// cannot handle null. @Override public boolean addAll(Collection collection) { return super.addAll(collection); } - /** - * Removes all elements from this {@code TreeSet}, leaving it empty. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this `TreeSet`, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size @Override public void clear() { backingMap.clear(); } - /** - * Returns the comparator used to compare elements in this {@code TreeSet}. - * - * @return a Comparator or null if the natural ordering is used - */ + /// Returns the comparator used to compare elements in this `TreeSet`. + /// + /// #### Returns + /// + /// a Comparator or null if the natural ordering is used public Comparator comparator() { return backingMap.comparator(); } - /** - * Searches this {@code TreeSet} for the specified object. - * - * @param object - * the object to search for. - * @return {@code true} if {@code object} is an element of this - * {@code TreeSet}, {@code false} otherwise. - * @throws ClassCastException - * when the object cannot be compared with the elements in this - * {@code TreeSet}. - * @throws NullPointerException - * when the object is null and the comparator cannot handle - * null. - */ + /// Searches this `TreeSet` for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to search for. + /// + /// #### Returns + /// + /// @return `true` if `object` is an element of this + /// `TreeSet`, `false` otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the object cannot be compared with the elements in this + /// `TreeSet`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the object is null and the comparator cannot handle + /// null. @Override public boolean contains(Object object) { return backingMap.containsKey(object); } - /** - * Returns true if this {@code TreeSet} has no element, otherwise false. - * - * @return true if this {@code TreeSet} has no element. - * @see #size - */ + /// Returns true if this `TreeSet` has no element, otherwise false. + /// + /// #### Returns + /// + /// true if this `TreeSet` has no element. + /// + /// #### See also + /// + /// - #size @Override public boolean isEmpty() { return backingMap.isEmpty(); } - /** - * Returns an Iterator on the elements of this {@code TreeSet}. - * - * @return an Iterator on the elements of this {@code TreeSet}. - * @see Iterator - */ + /// Returns an Iterator on the elements of this `TreeSet`. + /// + /// #### Returns + /// + /// an Iterator on the elements of this `TreeSet`. + /// + /// #### See also + /// + /// - Iterator @Override public Iterator iterator() { return backingMap.keySet().iterator(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#descendingIterator() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#descendingIterator() public Iterator descendingIterator() { return descendingSet().iterator(); } - /** - * Removes an occurrence of the specified object from this {@code TreeSet}. - * - * @param object - * the object to remove. - * @return {@code true} if this {@code TreeSet} was modified, {@code false} - * otherwise. - * @throws ClassCastException - * when the object cannot be compared with the elements in this - * {@code TreeSet}. - * @throws NullPointerException - * when the object is null and the comparator cannot handle - * null. - */ + /// Removes an occurrence of the specified object from this `TreeSet`. + /// + /// #### Parameters + /// + /// - `object`: the object to remove. + /// + /// #### Returns + /// + /// @return `true` if this `TreeSet` was modified, `false` + /// otherwise. + /// + /// #### Throws + /// + /// - `ClassCastException`: @throws ClassCastException + /// when the object cannot be compared with the elements in this + /// `TreeSet`. + /// + /// - `NullPointerException`: @throws NullPointerException + /// when the object is null and the comparator cannot handle + /// null. @Override public boolean remove(Object object) { return backingMap.remove(object) != null; } - /** - * Returns the number of elements in this {@code TreeSet}. - * - * @return the number of elements in this {@code TreeSet}. - */ + /// Returns the number of elements in this `TreeSet`. + /// + /// #### Returns + /// + /// the number of elements in this `TreeSet`. @Override public int size() { return backingMap.size(); } - /** - * Answers the first element in this TreeSet. - * - * @return the first element - * - * @exception NoSuchElementException - * when this TreeSet is empty - */ + /// Answers the first element in this TreeSet. + /// + /// #### Returns + /// + /// the first element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: when this TreeSet is empty public E first() { return backingMap.firstKey(); } - /** - * Answers the last element in this TreeSet. - * - * @return the last element - * - * @exception NoSuchElementException - * when this TreeSet is empty - */ + /// Answers the last element in this TreeSet. + /// + /// #### Returns + /// + /// the last element + /// + /// #### Throws + /// + /// - `NoSuchElementException`: when this TreeSet is empty public E last() { return backingMap.lastKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#pollFirst() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#pollFirst() public E pollFirst() { Map.Entry entry = backingMap.pollFirstEntry(); return (null == entry) ? null : entry.getKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#pollLast() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#pollLast() public E pollLast() { Map.Entry entry = backingMap.pollLastEntry(); return (null == entry) ? null : entry.getKey(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#higher(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#higher(java.lang.Object) public E higher(E e) { return backingMap.higherKey(e); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#lower(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#lower(java.lang.Object) public E lower(E e) { return backingMap.lowerKey(e); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#ceiling(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#ceiling(java.lang.Object) public E ceiling(E e) { return backingMap.ceilingKey(e); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#floor(java.lang.Object) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#floor(java.lang.Object) public E floor(E e) { return backingMap.floorKey(e); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#descendingSet() - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#descendingSet() public NavigableSet descendingSet() { return (null != descendingSet) ? descendingSet : (descendingSet = new TreeSet(backingMap.descendingMap())); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#subSet(Object, boolean, Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#subSet(Object, boolean, Object, boolean) @SuppressWarnings("unchecked") public NavigableSet subSet(E start, boolean startInclusive, E end, boolean endInclusive) { @@ -340,12 +398,15 @@ public NavigableSet subSet(E start, boolean startInclusive, E end, throw new IllegalArgumentException(); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#headSet(Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#headSet(Object, boolean) @SuppressWarnings("unchecked") public NavigableSet headSet(E end, boolean endInclusive) { // Check for errors @@ -358,12 +419,15 @@ public NavigableSet headSet(E end, boolean endInclusive) { return new TreeSet(backingMap.headMap(end, endInclusive)); } - /** - * {@inheritDoc} - * - * @see java.util.NavigableSet#tailSet(Object, boolean) - * @since 1.6 - */ + /// {@inheritDoc} + /// + /// #### Since + /// + /// 1.6 + /// + /// #### See also + /// + /// - java.util.NavigableSet#tailSet(Object, boolean) @SuppressWarnings("unchecked") public NavigableSet tailSet(E start, boolean startInclusive) { // Check for errors @@ -376,70 +440,85 @@ public NavigableSet tailSet(E start, boolean startInclusive) { return new TreeSet(backingMap.tailMap(start, startInclusive)); } - /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements greater or equal to the start element but less than the - * end element. The returned SortedSet is backed by this TreeSet so changes - * to one are reflected by the other. - * - * @param start - * the start element - * @param end - * the end element - * @return a subset where the elements are greater or equal to - * start and less than end - * - * @exception ClassCastException - * when the start or end object cannot be compared with the - * elements in this TreeSet - * @exception NullPointerException - * when the start or end object is null and the comparator - * cannot handle null - */ + /// Answers a SortedSet of the specified portion of this TreeSet which + /// contains elements greater or equal to the start element but less than the + /// end element. The returned SortedSet is backed by this TreeSet so changes + /// to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the start element + /// + /// - `end`: the end element + /// + /// #### Returns + /// + /// @return a subset where the elements are greater or equal to + /// `start` and less than `end` + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the start or end object cannot be compared with the + /// elements in this TreeSet + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the start or end object is null and the comparator + /// cannot handle null @SuppressWarnings("unchecked") public SortedSet subSet(E start, E end) { return subSet(start, true, end, false); } - /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements less than the end element. The returned SortedSet is - * backed by this TreeSet so changes to one are reflected by the other. - * - * @param end - * the end element - * @return a subset where the elements are less than end - * - * @exception ClassCastException - * when the end object cannot be compared with the elements - * in this TreeSet - * @exception NullPointerException - * when the end object is null and the comparator cannot - * handle null - */ + /// Answers a SortedSet of the specified portion of this TreeSet which + /// contains elements less than the end element. The returned SortedSet is + /// backed by this TreeSet so changes to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `end`: the end element + /// + /// #### Returns + /// + /// a subset where the elements are less than `end` + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the end object cannot be compared with the elements + /// in this TreeSet + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the end object is null and the comparator cannot + /// handle null @SuppressWarnings("unchecked") public SortedSet headSet(E end) { return headSet(end, false); } - /** - * Answers a SortedSet of the specified portion of this TreeSet which - * contains elements greater or equal to the start element. The returned - * SortedSet is backed by this TreeSet so changes to one are reflected by - * the other. - * - * @param start - * the start element - * @return a subset where the elements are greater or equal to - * start - * - * @exception ClassCastException - * when the start object cannot be compared with the elements - * in this TreeSet - * @exception NullPointerException - * when the start object is null and the comparator cannot - * handle null - */ + /// Answers a SortedSet of the specified portion of this TreeSet which + /// contains elements greater or equal to the start element. The returned + /// SortedSet is backed by this TreeSet so changes to one are reflected by + /// the other. + /// + /// #### Parameters + /// + /// - `start`: the start element + /// + /// #### Returns + /// + /// @return a subset where the elements are greater or equal to + /// `start` + /// + /// #### Throws + /// + /// - `ClassCastException`: @exception ClassCastException + /// when the start object cannot be compared with the elements + /// in this TreeSet + /// + /// - `NullPointerException`: @exception NullPointerException + /// when the start object is null and the comparator cannot + /// handle null @SuppressWarnings("unchecked") public SortedSet tailSet(E start) { return tailSet(start, true); diff --git a/Ports/CLDC11/src/java/util/Vector.java b/Ports/CLDC11/src/java/util/Vector.java index 70b8639844..e23c475a21 100644 --- a/Ports/CLDC11/src/java/util/Vector.java +++ b/Ports/CLDC11/src/java/util/Vector.java @@ -17,74 +17,68 @@ package java.util; -/** - * Vector is a variable size contiguous indexable array of objects. The size of - * the vector is the number of objects it contains. The capacity of the vector - * is the number of objects it can hold. - *

- * Objects may be inserted at any position up to the size of the vector, thus - * increasing the size of the vector. Objects at any position in the vector may - * be removed, thus shrinking the size of the Vector. Objects at any position in - * the Vector may be replaced, which does not affect the vector's size. - *

- * The capacity of a vector may be specified when the vector is created. If the - * capacity of the vector is exceeded, the capacity is increased (doubled by - * default). - * - * @see java.lang.StringBuffer - */ +/// Vector is a variable size contiguous indexable array of objects. The size of +/// the vector is the number of objects it contains. The capacity of the vector +/// is the number of objects it can hold. +/// +/// Objects may be inserted at any position up to the size of the vector, thus +/// increasing the size of the vector. Objects at any position in the vector may +/// be removed, thus shrinking the size of the Vector. Objects at any position in +/// the Vector may be replaced, which does not affect the vector's size. +/// +/// The capacity of a vector may be specified when the vector is created. If the +/// capacity of the vector is exceeded, the capacity is increased (doubled by +/// default). +/// +/// #### See also +/// +/// - java.lang.StringBuffer public class Vector extends AbstractList implements List, RandomAccess { - /** - * The number of elements or the size of the vector. - */ + /// The number of elements or the size of the vector. protected int elementCount; - /** - * The elements of the vector. - */ + /// The elements of the vector. protected Object[] elementData; - /** - * How many elements should be added to the vector when it is detected that - * it needs to grow to accommodate extra entries. If this value is zero or - * negative the size will be doubled if an increase is needed. - */ + /// How many elements should be added to the vector when it is detected that + /// it needs to grow to accommodate extra entries. If this value is zero or + /// negative the size will be doubled if an increase is needed. protected int capacityIncrement; private static final int DEFAULT_SIZE = 10; - /** - * Constructs a new vector using the default capacity. - */ + /// Constructs a new vector using the default capacity. public Vector() { this(DEFAULT_SIZE, 0); } - /** - * Constructs a new vector using the specified capacity. - * - * @param capacity - * the initial capacity of the new vector. - * @throws IllegalArgumentException - * if {@code capacity} is negative. - */ + /// Constructs a new vector using the specified capacity. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of the new vector. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `capacity` is negative. public Vector(int capacity) { this(capacity, 0); } - /** - * Constructs a new vector using the specified capacity and capacity - * increment. - * - * @param capacity - * the initial capacity of the new vector. - * @param capacityIncrement - * the amount to increase the capacity when this vector is full. - * @throws IllegalArgumentException - * if {@code capacity} is negative. - */ + /// Constructs a new vector using the specified capacity and capacity + /// increment. + /// + /// #### Parameters + /// + /// - `capacity`: the initial capacity of the new vector. + /// + /// - `capacityIncrement`: the amount to increase the capacity when this vector is full. + /// + /// #### Throws + /// + /// - `IllegalArgumentException`: if `capacity` is negative. public Vector(int capacity, int capacityIncrement) { if (capacity < 0) { throw new IllegalArgumentException(); @@ -94,14 +88,13 @@ public Vector(int capacity, int capacityIncrement) { this.capacityIncrement = capacityIncrement; } - /** - * Constructs a new instance of {@code Vector} containing the elements in - * {@code collection}. The order of the elements in the new {@code Vector} - * is dependent on the iteration order of the seed collection. - * - * @param collection - * the collection of elements to add. - */ + /// Constructs a new instance of `Vector` containing the elements in + /// `collection`. The order of the elements in the new `Vector` + /// is dependent on the iteration order of the seed collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of elements to add. public Vector(Collection collection) { this(collection.size(), 0); Iterator it = collection.iterator(); @@ -115,33 +108,40 @@ private E[] newElementArray(int size) { return (E[]) new Object[size]; } - /** - * Adds the specified object into this vector at the specified location. The - * object is inserted before any element with the same or a higher index - * increasing their index by 1. If the location is equal to the size of this - * vector, the object is added at the end. - * - * @param location - * the index at which to insert the element. - * @param object - * the object to insert in this vector. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location > size()}. - * @see #addElement - * @see #size - */ + /// Adds the specified object into this vector at the specified location. The + /// object is inserted before any element with the same or a higher index + /// increasing their index by 1. If the location is equal to the size of this + /// vector, the object is added at the end. + /// + /// #### Parameters + /// + /// - `location`: the index at which to insert the element. + /// + /// - `object`: the object to insert in this vector. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location size()`. + /// + /// #### See also + /// + /// - #addElement + /// + /// - #size @Override public void add(int location, E object) { insertElementAt(object, location); } - /** - * Adds the specified object at the end of this vector. - * - * @param object - * the object to add to the vector. - * @return {@code true} - */ + /// Adds the specified object at the end of this vector. + /// + /// #### Parameters + /// + /// - `object`: the object to add to the vector. + /// + /// #### Returns + /// + /// `true` @Override public synchronized boolean add(E object) { if (elementCount == elementData.length) { @@ -152,21 +152,25 @@ public synchronized boolean add(E object) { return true; } - /** - * Inserts the objects in the specified collection at the specified location - * in this vector. The objects are inserted in the order in which they are - * returned from the Collection iterator. The elements with an index equal - * or higher than {@code location} have their index increased by the size of - * the added collection. - * - * @param location - * the location to insert the objects. - * @param collection - * the collection of objects. - * @return {@code true} if this vector is modified, {@code false} otherwise. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0} or {@code location > size()}. - */ + /// Inserts the objects in the specified collection at the specified location + /// in this vector. The objects are inserted in the order in which they are + /// returned from the Collection iterator. The elements with an index equal + /// or higher than `location` have their index increased by the size of + /// the added collection. + /// + /// #### Parameters + /// + /// - `location`: the location to insert the objects. + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// `true` if this vector is modified, `false` otherwise. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location size()`. @Override public synchronized boolean addAll(int location, Collection collection) { @@ -195,24 +199,25 @@ public synchronized boolean addAll(int location, throw new ArrayIndexOutOfBoundsException(location); } - /** - * Adds the objects in the specified collection to the end of this vector. - * - * @param collection - * the collection of objects. - * @return {@code true} if this vector is modified, {@code false} otherwise. - */ + /// Adds the objects in the specified collection to the end of this vector. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// `true` if this vector is modified, `false` otherwise. @Override public synchronized boolean addAll(Collection collection) { return addAll(elementCount, collection); } - /** - * Adds the specified object at the end of this vector. - * - * @param object - * the object to add to the vector. - */ + /// Adds the specified object at the end of this vector. + /// + /// #### Parameters + /// + /// - `object`: the object to add to the vector. public synchronized void addElement(E object) { if (elementCount == elementData.length) { growByOne(); @@ -221,82 +226,108 @@ public synchronized void addElement(E object) { modCount++; } - /** - * Returns the number of elements this vector can hold without growing. - * - * @return the capacity of this vector. - * @see #ensureCapacity - * @see #size - */ + /// Returns the number of elements this vector can hold without growing. + /// + /// #### Returns + /// + /// the capacity of this vector. + /// + /// #### See also + /// + /// - #ensureCapacity + /// + /// - #size public synchronized int capacity() { return elementData.length; } - /** - * Removes all elements from this vector, leaving it empty. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this vector, leaving it empty. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size @Override public void clear() { removeAllElements(); } - /** - * Searches this vector for the specified object. - * - * @param object - * the object to look for in this vector. - * @return {@code true} if object is an element of this vector, - * {@code false} otherwise. - * @see #indexOf(Object) - * @see #indexOf(Object, int) - * @see java.lang.Object#equals - */ + /// Searches this vector for the specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to look for in this vector. + /// + /// #### Returns + /// + /// @return `true` if object is an element of this vector, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #indexOf(Object) + /// + /// - #indexOf(Object, int) + /// + /// - java.lang.Object#equals @Override public boolean contains(Object object) { return indexOf(object, 0) != -1; } - /** - * Searches this vector for all objects in the specified collection. - * - * @param collection - * the collection of objects. - * @return {@code true} if all objects in the specified collection are - * elements of this vector, {@code false} otherwise. - */ + /// Searches this vector for all objects in the specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects. + /// + /// #### Returns + /// + /// @return `true` if all objects in the specified collection are + /// elements of this vector, `false` otherwise. @Override public synchronized boolean containsAll(Collection collection) { return super.containsAll(collection); } - /** - * Attempts to copy elements contained by this {@code Vector} into the - * corresponding elements of the supplied {@code Object} array. - * - * @param elements - * the {@code Object} array into which the elements of this - * vector are copied. - * @throws IndexOutOfBoundsException - * if {@code elements} is not big enough. - * @see #clone - */ + /// Attempts to copy elements contained by this `Vector` into the + /// corresponding elements of the supplied `Object` array. + /// + /// #### Parameters + /// + /// - `elements`: @param elements + /// the `Object` array into which the elements of this + /// vector are copied. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `elements` is not big enough. + /// + /// #### See also + /// + /// - #clone public synchronized void copyInto(Object[] elements) { System.arraycopy(elementData, 0, elements, 0, elementCount); } - /** - * Returns the element at the specified location in this vector. - * - * @param location - * the index of the element to return in this vector. - * @return the element at the specified location. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - * @see #size - */ + /// Returns the element at the specified location in this vector. + /// + /// #### Parameters + /// + /// - `location`: the index of the element to return in this vector. + /// + /// #### Returns + /// + /// the element at the specified location. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location = size()`. + /// + /// #### See also + /// + /// - #size @SuppressWarnings("unchecked") public synchronized E elementAt(int location) { if (location < elementCount) { @@ -305,14 +336,18 @@ public synchronized E elementAt(int location) { throw new ArrayIndexOutOfBoundsException(location); } - /** - * Returns an enumeration on the elements of this vector. The results of the - * enumeration may be affected if the contents of this vector is modified. - * - * @return an enumeration of the elements of this vector. - * @see #elementAt - * @see Enumeration - */ + /// Returns an enumeration on the elements of this vector. The results of the + /// enumeration may be affected if the contents of this vector is modified. + /// + /// #### Returns + /// + /// an enumeration of the elements of this vector. + /// + /// #### See also + /// + /// - #elementAt + /// + /// - Enumeration public java.util.Enumeration elements() { return new java.util.Enumeration() { int pos = 0; @@ -333,15 +368,18 @@ public E nextElement() { }; } - /** - * Ensures that this vector can hold the specified number of elements - * without growing. - * - * @param minimumCapacity - * the minimum number of elements that this vector will hold - * before growing. - * @see #capacity - */ + /// Ensures that this vector can hold the specified number of elements + /// without growing. + /// + /// #### Parameters + /// + /// - `minimumCapacity`: @param minimumCapacity + /// the minimum number of elements that this vector will hold + /// before growing. + /// + /// #### See also + /// + /// - #capacity public synchronized void ensureCapacity(int minimumCapacity) { if (elementData.length < minimumCapacity) { int next = (capacityIncrement <= 0 ? elementData.length @@ -351,17 +389,22 @@ public synchronized void ensureCapacity(int minimumCapacity) { } } - /** - * Compares the specified object to this vector and returns if they are - * equal. The object must be a List which contains the same objects in the - * same order. - * - * @param object - * the object to compare with this object - * @return {@code true} if the specified object is equal to this vector, - * {@code false} otherwise. - * @see #hashCode - */ + /// Compares the specified object to this vector and returns if they are + /// equal. The object must be a List which contains the same objects in the + /// same order. + /// + /// #### Parameters + /// + /// - `object`: the object to compare with this object + /// + /// #### Returns + /// + /// @return `true` if the specified object is equal to this vector, + /// `false` otherwise. + /// + /// #### See also + /// + /// - #hashCode @Override public synchronized boolean equals(Object object) { if (this == object) { @@ -386,16 +429,23 @@ public synchronized boolean equals(Object object) { return false; } - /** - * Returns the first element in this vector. - * - * @return the element at the first position. - * @throws NoSuchElementException - * if this vector is empty. - * @see #elementAt - * @see #lastElement - * @see #size - */ + /// Returns the first element in this vector. + /// + /// #### Returns + /// + /// the element at the first position. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this vector is empty. + /// + /// #### See also + /// + /// - #elementAt + /// + /// - #lastElement + /// + /// - #size @SuppressWarnings("unchecked") public synchronized E firstElement() { if (elementCount > 0) { @@ -404,16 +454,23 @@ public synchronized E firstElement() { throw new NoSuchElementException(); } - /** - * Returns the element at the specified location in this vector. - * - * @param location - * the index of the element to return in this vector. - * @return the element at the specified location. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - * @see #size - */ + /// Returns the element at the specified location in this vector. + /// + /// #### Parameters + /// + /// - `location`: the index of the element to return in this vector. + /// + /// #### Returns + /// + /// the element at the specified location. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location = size()`. + /// + /// #### See also + /// + /// - #size @Override public E get(int location) { return elementAt(location); @@ -426,9 +483,7 @@ private void grow(int newCapacity) { elementData = newData; } - /** - * JIT optimization - */ + /// JIT optimization private void growByOne() { int adding = 0; if (capacityIncrement <= 0) { @@ -464,13 +519,16 @@ private void growBy(int required) { elementData = newData; } - /** - * Returns an integer hash code for the receiver. Objects which are equal - * return the same value for this method. - * - * @return the receiver's hash. - * @see #equals - */ + /// Returns an integer hash code for the receiver. Objects which are equal + /// return the same value for this method. + /// + /// #### Returns + /// + /// the receiver's hash. + /// + /// #### See also + /// + /// - #equals @Override public synchronized int hashCode() { int result = 1; @@ -481,41 +539,57 @@ public synchronized int hashCode() { return result; } - /** - * Searches in this vector for the index of the specified object. The search - * for the object starts at the beginning and moves towards the end of this - * vector. - * - * @param object - * the object to find in this vector. - * @return the index in this vector of the specified element, -1 if the - * element isn't found. - * @see #contains - * @see #lastIndexOf(Object) - * @see #lastIndexOf(Object, int) - */ + /// Searches in this vector for the index of the specified object. The search + /// for the object starts at the beginning and moves towards the end of this + /// vector. + /// + /// #### Parameters + /// + /// - `object`: the object to find in this vector. + /// + /// #### Returns + /// + /// @return the index in this vector of the specified element, -1 if the + /// element isn't found. + /// + /// #### See also + /// + /// - #contains + /// + /// - #lastIndexOf(Object) + /// + /// - #lastIndexOf(Object, int) @Override public int indexOf(Object object) { return indexOf(object, 0); } - /** - * Searches in this vector for the index of the specified object. The search - * for the object starts at the specified location and moves towards the end - * of this vector. - * - * @param object - * the object to find in this vector. - * @param location - * the index at which to start searching. - * @return the index in this vector of the specified element, -1 if the - * element isn't found. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0}. - * @see #contains - * @see #lastIndexOf(Object) - * @see #lastIndexOf(Object, int) - */ + /// Searches in this vector for the index of the specified object. The search + /// for the object starts at the specified location and moves towards the end + /// of this vector. + /// + /// #### Parameters + /// + /// - `object`: the object to find in this vector. + /// + /// - `location`: the index at which to start searching. + /// + /// #### Returns + /// + /// @return the index in this vector of the specified element, -1 if the + /// element isn't found. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location < 0`. + /// + /// #### See also + /// + /// - #contains + /// + /// - #lastIndexOf(Object) + /// + /// - #lastIndexOf(Object, int) public synchronized int indexOf(Object object, int location) { if (object != null) { for (int i = location; i < elementCount; i++) { @@ -533,22 +607,27 @@ public synchronized int indexOf(Object object, int location) { return -1; } - /** - * Inserts the specified object into this vector at the specified location. - * This object is inserted before any previous element at the specified - * location. All elements with an index equal or greater than - * {@code location} have their index increased by 1. If the location is - * equal to the size of this vector, the object is added at the end. - * - * @param object - * the object to insert in this vector. - * @param location - * the index at which to insert the element. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location > size()}. - * @see #addElement - * @see #size - */ + /// Inserts the specified object into this vector at the specified location. + /// This object is inserted before any previous element at the specified + /// location. All elements with an index equal or greater than + /// `location` have their index increased by 1. If the location is + /// equal to the size of this vector, the object is added at the end. + /// + /// #### Parameters + /// + /// - `object`: the object to insert in this vector. + /// + /// - `location`: the index at which to insert the element. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location size()`. + /// + /// #### See also + /// + /// - #addElement + /// + /// - #size public synchronized void insertElementAt(E object, int location) { if (0 <= location && location <= elementCount) { if (elementCount == elementData.length) { @@ -567,28 +646,38 @@ public synchronized void insertElementAt(E object, int location) { } } - /** - * Returns if this vector has no elements, a size of zero. - * - * @return {@code true} if this vector has no elements, {@code false} - * otherwise. - * @see #size - */ + /// Returns if this vector has no elements, a size of zero. + /// + /// #### Returns + /// + /// @return `true` if this vector has no elements, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #size @Override public synchronized boolean isEmpty() { return elementCount == 0; } - /** - * Returns the last element in this vector. - * - * @return the element at the last position. - * @throws NoSuchElementException - * if this vector is empty. - * @see #elementAt - * @see #firstElement - * @see #size - */ + /// Returns the last element in this vector. + /// + /// #### Returns + /// + /// the element at the last position. + /// + /// #### Throws + /// + /// - `NoSuchElementException`: if this vector is empty. + /// + /// #### See also + /// + /// - #elementAt + /// + /// - #firstElement + /// + /// - #size @SuppressWarnings("unchecked") public synchronized E lastElement() { try { @@ -598,41 +687,57 @@ public synchronized E lastElement() { } } - /** - * Searches in this vector for the index of the specified object. The search - * for the object starts at the end and moves towards the start of this - * vector. - * - * @param object - * the object to find in this vector. - * @return the index in this vector of the specified element, -1 if the - * element isn't found. - * @see #contains - * @see #indexOf(Object) - * @see #indexOf(Object, int) - */ + /// Searches in this vector for the index of the specified object. The search + /// for the object starts at the end and moves towards the start of this + /// vector. + /// + /// #### Parameters + /// + /// - `object`: the object to find in this vector. + /// + /// #### Returns + /// + /// @return the index in this vector of the specified element, -1 if the + /// element isn't found. + /// + /// #### See also + /// + /// - #contains + /// + /// - #indexOf(Object) + /// + /// - #indexOf(Object, int) @Override public synchronized int lastIndexOf(Object object) { return lastIndexOf(object, elementCount - 1); } - /** - * Searches in this vector for the index of the specified object. The search - * for the object starts at the specified location and moves towards the - * start of this vector. - * - * @param object - * the object to find in this vector. - * @param location - * the index at which to start searching. - * @return the index in this vector of the specified element, -1 if the - * element isn't found. - * @throws ArrayIndexOutOfBoundsException - * if {@code location >= size()}. - * @see #contains - * @see #indexOf(Object) - * @see #indexOf(Object, int) - */ + /// Searches in this vector for the index of the specified object. The search + /// for the object starts at the specified location and moves towards the + /// start of this vector. + /// + /// #### Parameters + /// + /// - `object`: the object to find in this vector. + /// + /// - `location`: the index at which to start searching. + /// + /// #### Returns + /// + /// @return the index in this vector of the specified element, -1 if the + /// element isn't found. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location >= size()`. + /// + /// #### See also + /// + /// - #contains + /// + /// - #indexOf(Object) + /// + /// - #indexOf(Object, int) public synchronized int lastIndexOf(Object object, int location) { if (location < elementCount) { if (object != null) { @@ -653,17 +758,21 @@ public synchronized int lastIndexOf(Object object, int location) { throw new ArrayIndexOutOfBoundsException(location); } - /** - * Removes the object at the specified location from this vector. All - * elements with an index bigger than {@code location} have their index - * decreased by 1. - * - * @param location - * the index of the object to remove. - * @return the removed object. - * @throws IndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - */ + /// Removes the object at the specified location from this vector. All + /// elements with an index bigger than `location` have their index + /// decreased by 1. + /// + /// #### Parameters + /// + /// - `location`: the index of the object to remove. + /// + /// #### Returns + /// + /// the removed object. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `location = size()`. @SuppressWarnings("unchecked") @Override public synchronized E remove(int location) { @@ -682,47 +791,61 @@ public synchronized E remove(int location) { throw new ArrayIndexOutOfBoundsException(location); } - /** - * Removes the first occurrence, starting at the beginning and moving - * towards the end, of the specified object from this vector. All elements - * with an index bigger than the element that gets removed have their index - * decreased by 1. - * - * @param object - * the object to remove from this vector. - * @return {@code true} if the specified object was found, {@code false} - * otherwise. - * @see #removeAllElements - * @see #removeElementAt - * @see #size - */ + /// Removes the first occurrence, starting at the beginning and moving + /// towards the end, of the specified object from this vector. All elements + /// with an index bigger than the element that gets removed have their index + /// decreased by 1. + /// + /// #### Parameters + /// + /// - `object`: the object to remove from this vector. + /// + /// #### Returns + /// + /// @return `true` if the specified object was found, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #removeAllElements + /// + /// - #removeElementAt + /// + /// - #size @Override public boolean remove(Object object) { return removeElement(object); } - /** - * Removes all occurrences in this vector of each object in the specified - * Collection. - * - * @param collection - * the collection of objects to remove. - * @return {@code true} if this vector is modified, {@code false} otherwise. - * @see #remove(Object) - * @see #contains(Object) - */ + /// Removes all occurrences in this vector of each object in the specified + /// Collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to remove. + /// + /// #### Returns + /// + /// `true` if this vector is modified, `false` otherwise. + /// + /// #### See also + /// + /// - #remove(Object) + /// + /// - #contains(Object) @Override public synchronized boolean removeAll(Collection collection) { return super.removeAll(collection); } - /** - * Removes all elements from this vector, leaving the size zero and the - * capacity unchanged. - * - * @see #isEmpty - * @see #size - */ + /// Removes all elements from this vector, leaving the size zero and the + /// capacity unchanged. + /// + /// #### See also + /// + /// - #isEmpty + /// + /// - #size public synchronized void removeAllElements() { for (int i = 0; i < elementCount; i++) { elementData[i] = null; @@ -731,20 +854,27 @@ public synchronized void removeAllElements() { elementCount = 0; } - /** - * Removes the first occurrence, starting at the beginning and moving - * towards the end, of the specified object from this vector. All elements - * with an index bigger than the element that gets removed have their index - * decreased by 1. - * - * @param object - * the object to remove from this vector. - * @return {@code true} if the specified object was found, {@code false} - * otherwise. - * @see #removeAllElements - * @see #removeElementAt - * @see #size - */ + /// Removes the first occurrence, starting at the beginning and moving + /// towards the end, of the specified object from this vector. All elements + /// with an index bigger than the element that gets removed have their index + /// decreased by 1. + /// + /// #### Parameters + /// + /// - `object`: the object to remove from this vector. + /// + /// #### Returns + /// + /// @return `true` if the specified object was found, `false` + /// otherwise. + /// + /// #### See also + /// + /// - #removeAllElements + /// + /// - #removeElementAt + /// + /// - #size public synchronized boolean removeElement(Object object) { int index; if ((index = indexOf(object, 0)) == -1) { @@ -754,19 +884,25 @@ public synchronized boolean removeElement(Object object) { return true; } - /** - * Removes the element found at index position {@code location} from - * this {@code Vector}. All elements with an index bigger than - * {@code location} have their index decreased by 1. - * - * @param location - * the index of the element to remove. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - * @see #removeElement - * @see #removeAllElements - * @see #size - */ + /// Removes the element found at index position `location` from + /// this `Vector`. All elements with an index bigger than + /// `location` have their index decreased by 1. + /// + /// #### Parameters + /// + /// - `location`: the index of the element to remove. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location = size()`. + /// + /// #### See also + /// + /// - #removeElement + /// + /// - #removeAllElements + /// + /// - #size public synchronized void removeElementAt(int location) { if (0 <= location && location < elementCount) { elementCount--; @@ -782,19 +918,21 @@ public synchronized void removeElementAt(int location) { } } - /** - * Removes the objects in the specified range from the start to the, but not - * including, end index. All elements with an index bigger than or equal to - * {@code end} have their index decreased by {@code end - start}. - * - * @param start - * the index at which to start removing. - * @param end - * the index one past the end of the range to remove. - * @throws IndexOutOfBoundsException - * if {@code start < 0, start > end} or - * {@code end > size()}. - */ + /// Removes the objects in the specified range from the start to the, but not + /// including, end index. All elements with an index bigger than or equal to + /// `end` have their index decreased by `end - start`. + /// + /// #### Parameters + /// + /// - `start`: the index at which to start removing. + /// + /// - `end`: the index one past the end of the range to remove. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: @throws IndexOutOfBoundsException + /// if `start end` or + /// `end > size()`. @Override protected void removeRange(int start, int end) { if (start >= 0 && start <= end && end <= elementCount) { @@ -817,33 +955,45 @@ protected void removeRange(int start, int end) { } } - /** - * Removes all objects from this vector that are not contained in the - * specified collection. - * - * @param collection - * the collection of objects to retain. - * @return {@code true} if this vector is modified, {@code false} otherwise. - * @see #remove(Object) - */ + /// Removes all objects from this vector that are not contained in the + /// specified collection. + /// + /// #### Parameters + /// + /// - `collection`: the collection of objects to retain. + /// + /// #### Returns + /// + /// `true` if this vector is modified, `false` otherwise. + /// + /// #### See also + /// + /// - #remove(Object) @Override public synchronized boolean retainAll(Collection collection) { return super.retainAll(collection); } - /** - * Replaces the element at the specified location in this vector with the - * specified object. - * - * @param location - * the index at which to put the specified object. - * @param object - * the object to add to this vector. - * @return the previous element at the location. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - * @see #size - */ + /// Replaces the element at the specified location in this vector with the + /// specified object. + /// + /// #### Parameters + /// + /// - `location`: the index at which to put the specified object. + /// + /// - `object`: the object to add to this vector. + /// + /// #### Returns + /// + /// the previous element at the location. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location = size()`. + /// + /// #### See also + /// + /// - #size @SuppressWarnings("unchecked") @Override public synchronized E set(int location, E object) { @@ -855,18 +1005,22 @@ public synchronized E set(int location, E object) { throw new ArrayIndexOutOfBoundsException(location); } - /** - * Replaces the element at the specified location in this vector with the - * specified object. - * - * @param object - * the object to add to this vector. - * @param location - * the index at which to put the specified object. - * @throws ArrayIndexOutOfBoundsException - * if {@code location < 0 || location >= size()}. - * @see #size - */ + /// Replaces the element at the specified location in this vector with the + /// specified object. + /// + /// #### Parameters + /// + /// - `object`: the object to add to this vector. + /// + /// - `location`: the index at which to put the specified object. + /// + /// #### Throws + /// + /// - `ArrayIndexOutOfBoundsException`: if `location = size()`. + /// + /// #### See also + /// + /// - #size public synchronized void setElementAt(E object, int location) { if (location < elementCount) { elementData[location] = object; @@ -875,16 +1029,18 @@ public synchronized void setElementAt(E object, int location) { } } - /** - * Sets the size of this vector to the specified size. If there are more - * than length elements in this vector, the elements at end are lost. If - * there are less than length elements in the vector, the additional - * elements contain null. - * - * @param length - * the new size of this vector. - * @see #size - */ + /// Sets the size of this vector to the specified size. If there are more + /// than length elements in this vector, the elements at end are lost. If + /// there are less than length elements in the vector, the additional + /// elements contain null. + /// + /// #### Parameters + /// + /// - `length`: the new size of this vector. + /// + /// #### See also + /// + /// - #size public synchronized void setSize(int length) { if (length == elementCount) { return; @@ -897,44 +1053,52 @@ public synchronized void setSize(int length) { modCount++; } - /** - * Returns the number of elements in this vector. - * - * @return the number of elements in this vector. - * @see #elementCount - * @see #lastElement - */ + /// Returns the number of elements in this vector. + /// + /// #### Returns + /// + /// the number of elements in this vector. + /// + /// #### See also + /// + /// - #elementCount + /// + /// - #lastElement @Override public synchronized int size() { return elementCount; } - /** - * Returns a List of the specified portion of this vector from the start - * index to one less than the end index. The returned List is backed by this - * vector so changes to one are reflected by the other. - * - * @param start - * the index at which to start the sublist. - * @param end - * the index one past the end of the sublist. - * @return a List of a portion of this vector. - * @throws IndexOutOfBoundsException - * if {@code start < 0} or {@code end > size()}. - * @throws IllegalArgumentException - * if {@code start > end}. - */ + /// Returns a List of the specified portion of this vector from the start + /// index to one less than the end index. The returned List is backed by this + /// vector so changes to one are reflected by the other. + /// + /// #### Parameters + /// + /// - `start`: the index at which to start the sublist. + /// + /// - `end`: the index one past the end of the sublist. + /// + /// #### Returns + /// + /// a List of a portion of this vector. + /// + /// #### Throws + /// + /// - `IndexOutOfBoundsException`: if `start size()`. + /// + /// - `IllegalArgumentException`: if `start > end`. @Override public synchronized List subList(int start, int end) { return new Collections.SynchronizedRandomAccessList(super.subList( start, end), this); } - /** - * Returns a new array containing all elements contained in this vector. - * - * @return an array of the elements from this vector. - */ + /// Returns a new array containing all elements contained in this vector. + /// + /// #### Returns + /// + /// an array of the elements from this vector. @Override public synchronized Object[] toArray() { Object[] result = new Object[elementCount]; @@ -942,20 +1106,25 @@ public synchronized Object[] toArray() { return result; } - /** - * Returns an array containing all elements contained in this vector. If the - * specified array is large enough to hold the elements, the specified array - * is used, otherwise an array of the same type is created. If the specified - * array is used and is larger than this vector, the array element following - * the collection elements is set to null. - * - * @param contents - * the array to fill. - * @return an array of the elements from this vector. - * @throws ArrayStoreException - * if the type of an element in this vector cannot be - * stored in the type of the specified array. - */ + /// Returns an array containing all elements contained in this vector. If the + /// specified array is large enough to hold the elements, the specified array + /// is used, otherwise an array of the same type is created. If the specified + /// array is used and is larger than this vector, the array element following + /// the collection elements is set to null. + /// + /// #### Parameters + /// + /// - `contents`: the array to fill. + /// + /// #### Returns + /// + /// an array of the elements from this vector. + /// + /// #### Throws + /// + /// - `ArrayStoreException`: @throws ArrayStoreException + /// if the type of an element in this vector cannot be + /// stored in the type of the specified array. @Override @SuppressWarnings("unchecked") public synchronized T[] toArray(T[] contents) { @@ -969,12 +1138,15 @@ public synchronized T[] toArray(T[] contents) { return contents; } - /** - * Returns the string representation of this vector. - * - * @return the string representation of this vector. - * @see #elements - */ + /// Returns the string representation of this vector. + /// + /// #### Returns + /// + /// the string representation of this vector. + /// + /// #### See also + /// + /// - #elements @Override public synchronized String toString() { if (elementCount == 0) { @@ -1000,13 +1172,15 @@ public synchronized String toString() { return buffer.toString(); } - /** - * Sets the capacity of this vector to be the same as the size. - * - * @see #capacity - * @see #ensureCapacity - * @see #size - */ + /// Sets the capacity of this vector to be the same as the size. + /// + /// #### See also + /// + /// - #capacity + /// + /// - #ensureCapacity + /// + /// - #size public synchronized void trimToSize() { if (elementData.length != elementCount) { grow(elementCount);