GP-4017: Fix Javadoc warnings

Ghidra/Framework/Emulation/src/main/java/ghidra/app/emulator/AdaptedMemoryState.java

@@ -25,8 +25,7 @@ import ghidra.pcode.exec.PcodeArithmetic;
 import ghidra.pcode.exec.PcodeArithmetic.Purpose;
 import ghidra.pcode.exec.PcodeExecutorState;
 import ghidra.pcode.exec.PcodeExecutorStatePiece.Reason;
-import ghidra.pcode.memstate.AbstractMemoryState;
+import ghidra.pcode.memstate.*;
-import ghidra.pcode.memstate.MemoryBank;
 import ghidra.program.model.address.AddressSpace;
 
 /**

Ghidra/Framework/Emulation/src/main/java/ghidra/lifecycle/Unfinished.java

@@ -17,7 +17,7 @@ package ghidra.lifecycle;
 
 /**
  * This serves both as a marker interface for classes missing important methods and as container for
- * the {@link #TODO(String, Object...))} method.
+ * the {@link #TODO(String, Object...)} method.
  * 
  * <p>
  * TODO: It'd be nice to optionally ignore TODO exceptions, but this seems to require a dependency

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/emu/DefaultPcodeThread.java

@@ -157,9 +157,7 @@ public class DefaultPcodeThread<T> implements PcodeThread<T> {
 		 * Construct the executor
 		 * 
 		 * @see DefaultPcodeThread#createExecutor()
-		 * @param language the language of the containing machine
+		 * @param thread the thread this executor supports
-		 * @param arithmetic the arithmetic of the containing machine
-		 * @param state the composite state assigned to the thread
 		 */
 		public PcodeThreadExecutor(DefaultPcodeThread<T> thread) {
 			// NB. The executor itself is not decoding. So reads are in fact data reads.

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/emu/PcodeEmulator.java

@@ -15,8 +15,7 @@
  */
 package ghidra.pcode.emu;
 
-import java.util.List;
+import ghidra.app.plugin.processors.sleigh.SleighLanguage;
-
 import ghidra.pcode.emu.auxiliary.AuxPcodeEmulator;
 import ghidra.pcode.exec.*;
 import ghidra.program.model.address.Address;
@@ -40,20 +39,20 @@ import ghidra.program.model.lang.Language;
  * or one of its derivatives to create a concrete-plus-auxiliary style emulator.
  * 
  * <pre>
- * emulator      : PcodeMachine<T>
+ * emulator      : {@link PcodeMachine}{@code <T>}
- *  - language     : SleighLanguage
+ *  - language     : {@link SleighLanguage}
- *  - arithmetic   : PcodeArithmetic<T>
+ *  - arithmetic   : {@link PcodeArithmetic}{@code <T>}
- *  - sharedState  : PcodeExecutorState<T>
+ *  - sharedState  : {@link PcodeExecutorState}{@code <T>}
- *  - library      : PcodeUseropLibrary<T>
+ *  - library      : {@link PcodeUseropLibrary}{@code <T>}
- *  - injects      : Map<Address, PcodeProgram>
+ *  - injects      : {@code Map<Address, }{@link PcodeProgram}{@code >}
- *  - threads      : List<PcodeThread<T>>
+ *  - threads      : {@code List<}{@link PcodeThread}{@code <T>>}
- *    - [0]          : PcodeThread<T>
+ *    - [0]          : {@link PcodeThread}{@code <T>}
- *      - decoder      : InstructionDecoder
+ *      - decoder      : {@link InstructionDecoder}
- *      - executor     : PcodeExecutor<T>
+ *      - executor     : {@link PcodeExecutor}{@code <T>}
- *      - frame        : PcodeFrame
+ *      - frame        : {@link PcodeFrame}
- *      - localState   : PcodeExecutorState<T>
+ *      - localState   : {@link PcodeExecutorState}{@code <T>}
- *      - library      : PcodeUseropLibrary<T>
+ *      - library      : {@link PcodeUseropLibrary}{@code <T>}
- *      - injects      : Map<Address, PcodeProgram>
+ *      - injects      : {@code Map<Address, }{@link PcodeProgram}{@code >}
  *    - [1] ...
  * </pre>
  * 
@@ -102,7 +101,7 @@ import ghidra.program.model.lang.Language;
  * Alternatively, if the target program never invokes system calls directly, but rather via
  * system-provided APIs, then it may suffice to stub out those imports. Typically, Ghidra will place
  * a "thunk" at each import address with the name of the import. Stubbing an import is accomplished
- * by injecting p-code at the import address. See {@link PcodeMachine#inject(Address, List)}. The
+ * by injecting p-code at the import address. See {@link PcodeMachine#inject(Address, String)}. The
  * inject will need to replicate the semantics of that call to the desired fidelity.
  * <b>IMPORTANT:</b> The inject must also return control to the calling function, usually by
  * replicating the conventions of the target platform.

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/emu/PcodeMachine.java

@@ -116,7 +116,6 @@ public interface PcodeMachine<T> {
 	 * continuing from a breakpoint.
 	 * 
 	 * @param mode the new mode
-	 * @see #withSoftwareInterruptMode(SwiMode)
 	 */
 	void setSoftwareInterruptMode(SwiMode mode);
 
@@ -206,7 +205,7 @@ public interface PcodeMachine<T> {
 	/**
 	 * Check the suspension state of the machine
 	 * 
-	 * @see PcodeThread#getSuspended()
+	 * @see PcodeThread#isSuspended()
 	 */
 	boolean isSuspended();
 
@@ -218,7 +217,7 @@ public interface PcodeMachine<T> {
 	 * userops, e.g., {@code emu_swi}.
 	 * 
 	 * @param sourceName a user-defined source name for the resulting "program"
-	 * @param lines the Sleigh source
+	 * @param source the Sleigh source
 	 * @return the compiled program
 	 */
 	PcodeProgram compileSleigh(String sourceName, String source);
@@ -296,8 +295,8 @@ public interface PcodeMachine<T> {
 	 * trapped. To interrupt on direct and/or abstract accesses, consider wrapping the relevant
 	 * state and/or overriding {@link PcodeExecutorStatePiece#getVar(Varnode, Reason)} and related.
 	 * For accesses to abstract offsets, consider overriding
-	 * {@link AbstractPcodeMachine#checkLoad(AddressSpace, Object)} and/or
+	 * {@link AbstractPcodeMachine#checkLoad(AddressSpace, Object, int)} and/or
-	 * {@link AbstractPcodeMachine#checkStore(AddressSpace, Object)} instead.
+	 * {@link AbstractPcodeMachine#checkStore(AddressSpace, Object, int)} instead.
 	 * 
 	 * <p>
 	 * A breakpoint's range cannot cross more than one page boundary. Pages are 4096 bytes each.

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/emu/PcodeThread.java

@@ -348,7 +348,7 @@ public interface PcodeThread<T> {
 	 * Override the p-code at the given address with the given Sleigh source for only this thread
 	 * 
 	 * <p>
-	 * This works the same {@link PcodeMachine#inject(Address, List)} but on a per-thread basis.
+	 * This works the same {@link PcodeMachine#inject(Address, String)} but on a per-thread basis.
 	 * Where there is both a machine-level and thread-level inject the thread inject takes
 	 * precedence. Furthermore, the machine-level inject cannot be accessed by the thread-level
 	 * inject.

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/BytesPcodeExecutorStatePiece.java

@@ -29,7 +29,7 @@ public class BytesPcodeExecutorStatePiece
 	/**
 	 * Construct a state for the given language
 	 * 
-	 * @param langauge the language (used for its memory model)
+	 * @param language the language (used for its memory model)
 	 */
 	public BytesPcodeExecutorStatePiece(Language language) {
 		super(language);

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/BytesPcodeExecutorStateSpace.java

@@ -165,8 +165,8 @@ public class BytesPcodeExecutorStateSpace<B> {
 	 * 
 	 * <p>
 	 * If this space is not acting as a cache, this simply delegates to
-	 * {@link #readBytes(long, int)}. Otherwise, it will first ensure the cache covers the requested
+	 * {@link #readBytes(long, int, Reason)}. Otherwise, it will first ensure the cache covers the
-	 * value.
+	 * requested value.
 	 * 
 	 * @param offset the offset
 	 * @param size the number of bytes to read (the size of the value)

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/InjectionErrorPcodeExecutionException.java

@@ -15,8 +15,10 @@
  */
 package ghidra.pcode.exec;
 
+import ghidra.pcode.emu.DefaultPcodeThread.PcodeEmulationLibrary;
+
 /**
- * Exception thrown by {@link PcodeEmulationLibrary#emu_injection_err(), a p-code userop invoked
+ * Exception thrown by {@link PcodeEmulationLibrary#emu_injection_err()}, a p-code userop invoked
  * when client-provided Sleigh code in an injection could not be compiled.
  */
 public class InjectionErrorPcodeExecutionException extends PcodeExecutionException {

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/LocationPcodeExecutorStatePiece.java

@@ -45,7 +45,7 @@ public class LocationPcodeExecutorStatePiece
 	/**
 	 * Construct a "location" state piece
 	 * 
-	 * @param isBigEndian true if the control language is big endian
+	 * @param language the language of the machine
 	 */
 	public LocationPcodeExecutorStatePiece(Language language) {
 		this.language = language;

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/PcodeArithmetic.java

@@ -146,8 +146,7 @@ public interface PcodeArithmetic<T> {
 	 * @implNote {@link OpBehaviorFactory#getOpBehavior(int)} for the given opcode is guaranteed to
 	 *           return a derivative of {@link BinaryOpBehavior}.
 	 * 
-	 * @param op the operation
+	 * @param opcode the operation's opcode. See {@link PcodeOp}.
-	 * @param b the behavior of the operator
 	 * @param sizeout the size (in bytes) of the output variable
 	 * @param sizein1 the size (in bytes) of the first (left) input variable
 	 * @param in1 the first (left) input value
@@ -168,9 +167,9 @@ public interface PcodeArithmetic<T> {
 	 * @implNote {@link OpBehaviorFactory#getOpBehavior(int)} for the given opcode is guaranteed to
 	 *           return a derivative of {@link BinaryOpBehavior}.
 	 * 
-	 * @param op
+	 * @param op the operation
-	 * @param in1
+	 * @param in1 the first (left) input value
-	 * @param in2
+	 * @param in2 the second (right) input value
 	 * @return the output value
 	 */
 	default T binaryOp(PcodeOp op, T in1, T in2) {
@@ -216,7 +215,7 @@ public interface PcodeArithmetic<T> {
 	 * The "pointer subfield" op takes two operands: base, offset; and is used as a more specific
 	 * representation of structure field address computation. Its behavior is exactly equivalent to
 	 * {@link PcodeOp#INT_ADD}. Suppose {@code st} is a structure pointer with a field {@code f}
-	 * located {@link offset} bytes into the structure, and {@code st} has the value {@code base}.
+	 * located {@code inOffset} bytes into the structure, and {@code st} has the value {@code base}.
 	 * The decompiler would likely render the {@link PcodeOp#PTRSUB} op as {@code &st->f}. An
 	 * equivalent SLEIGH expression is {@code base + offset}.
 	 * 
@@ -327,8 +326,7 @@ public interface PcodeArithmetic<T> {
 	 * Convert, if possible, the given abstract value to a concrete byte array
 	 * 
 	 * @param value the abstract value
-	 * @param size the expected size (in bytes) of the array
+	 * @param purpose the purpose for which the emulator needs a concrete value
-	 * @param the reason why the emulator needs a concrete value
 	 * @return the array
 	 * @throws ConcretionError if the value cannot be made concrete
 	 */

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/PcodeExecutorState.java

@@ -45,10 +45,10 @@ public interface PcodeExecutorState<T> extends PcodeExecutorStatePiece<T, T> {
 	 * 
 	 * <p>
 	 * <b>CAUTION:</b> Often, the default paired state is not quite sufficient. Consider
-	 * {@link #getVar(AddressSpace, Object, int, boolean)}. The rider on the offset may offer
+	 * {@link #getVar(AddressSpace, Object, int, boolean, Reason)}. The rider on the offset may
-	 * information that must be incorporated into the rider of the value just read. This is the
+	 * offer information that must be incorporated into the rider of the value just read. This is
-	 * case, for example, with taint propagation. In those cases, an anonymous inner class extending
+	 * the case, for example, with taint propagation. In those cases, an anonymous inner class
-	 * {@link PairedPcodeExecutorState} is sufficient.
+	 * extending {@link PairedPcodeExecutorState} is sufficient.
 	 * 
 	 * @param <U> the type of values and offsets stored by the rider
 	 * @param right the rider state

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/SleighLinkException.java

@@ -19,7 +19,7 @@ import ghidra.program.model.pcode.PcodeOp;
 
 /**
  * An exception thrown by
- * {@link PcodeExecutor#executeCallother(PcodeOp, PcodeFrame, PcodeUseropLibrary) when a p-code
+ * {@link PcodeExecutor#executeCallother(PcodeOp, PcodeFrame, PcodeUseropLibrary)} when a p-code
  * userop turns up missing.
  */
 public class SleighLinkException extends RuntimeException {

Ghidra/Framework/Emulation/src/main/java/ghidra/pcode/exec/SleighProgramCompiler.java

@@ -140,7 +140,7 @@ public enum SleighProgramCompiler {
 	/**
 	 * Compile the given source into a p-code template
 	 * 
-	 * @see #compileProgram(SleighLanguage, String, List, PcodeUseropLibrary)
+	 * @see #compileProgram(SleighLanguage, String, String, PcodeUseropLibrary)
 	 * @param language the language
 	 * @param parser the parser
 	 * @param sourceName the name of the program, for error diagnostics
@@ -249,7 +249,7 @@ public enum SleighProgramCompiler {
 	 * scripting, or perhaps in a Sleigh repl. The library given during compilation must match the
 	 * library given for execution, at least in its binding of userop IDs to symbols.
 	 * 
-	 * @param the parser to use
+	 * @param parser the parser to use
 	 * @param language the language of the target p-code machine
 	 * @param sourceName a diagnostic name for the Sleigh source
 	 * @param source the Sleigh source

Ghidra/Framework/Pty/src/main/java/ghidra/pty/PtyChild.java

@@ -80,9 +80,9 @@ public interface PtyChild extends PtyEndpoint {
 	 * Start a session without a real leader, instead obtaining the pty's name
 	 * 
 	 * <p>
-	 * This method or {@link #session(String[], Map, Collection)} can only be invoked once per pty.
+	 * This method or any other {@code session} method can only be invoked once per pty. It must be
-	 * It must be called before anyone reads the parent's output stream, since obtaining the
+	 * called before anyone reads the parent's output stream, since obtaining the filename may be
-	 * filename may be implemented by the parent sending commands to its child.
+	 * implemented by the parent sending commands to its child.
 	 * 
 	 * <p>
 	 * If the child end of the pty is on a remote system, this should be the file (or other

Ghidra/Framework/SoftwareModeling/src/main/java/ghidra/program/model/address/OverlayAddressSpace.java

@@ -41,7 +41,7 @@ public abstract class OverlayAddressSpace extends AbstractAddressSpace {
 
 	/**
 	 * Get the ordered key assigned to this overlay address space instance  This value is used
-	 * when performing {@link #equals(Object)} and {@link AddressSpace#compareTo(AddressSpace)}
+	 * when performing {@link #equals(Object)} and {@link #compareTo(AddressSpace)}
 	 * operations.
 	 * <p>
 	 * If this value does not have its optimal value (i.e., same as address space name), the