Mirrors_Framework/ghidra
1
0
Fork 0
mirror of https://github.com/NationalSecurityAgency/ghidra.git synced 2026-05-30 03:17:16 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

GP-5891: Include Debugger javadocs in the build.

Browse Source
This commit is contained in:
Dan
2025-08-11 13:12:28 +00:00
parent 483cd9a799
commit ce96f8551d
51 changed files with 223 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Ghidra/Debug/ProposedUtils/build.gradle
+1
View File
@@ -17,6 +17,7 @@ apply from: "${rootProject.projectDir}/gradle/javaProject.gradle"
apply from: "${rootProject.projectDir}/gradle/jacocoProject.gradle"
apply from: "${rootProject.projectDir}/gradle/javaTestProject.gradle"
apply from: "${rootProject.projectDir}/gradle/distributableGhidraModule.gradle"
apply from: "${rootProject.projectDir}/gradle/javadoc.gradle"
apply plugin: 'eclipse'
eclipse.project.name = 'Debug ProposedUtils'
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/graph/algo/TopologicalSorter.java
+8 -5
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -40,7 +40,10 @@ import ghidra.graph.*;
* <p>
* A-->B-->D, A-->C-->D yields either [A, B, C, D] or [A, C, B, D]
*
* @see {@link https://en.wikipedia.org/wiki/Topological_sorting}
* @see <a href="https://en.wikipedia.org/wiki/Topological_sorting">Wikipedia: Topological
* Sorting</a>
* @param <V> the type of vector
* @param <E> the type of edge
*/
public class TopologicalSorter<V, E extends GEdge<V>> {
private final GDirectedGraph<V, E> graph;
@@ -53,8 +56,8 @@ public class TopologicalSorter<V, E extends GEdge<V>> {
*
* @param graph the graph
* @param requireTotal true to require a unique solution
* @note if a unique solution is not requested, this algorithm will choose a solution
* arbitrarily. It does not yield all possible solutions.
* @implNote if a unique solution is not requested, this algorithm will choose a solution
* arbitrarily. It does not yield all possible solutions.
*/
public TopologicalSorter(GDirectedGraph<V, E> graph, boolean requireTotal) {
this.graph = graph;
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/pcode/eval/AbstractVarnodeEvaluator.java
+3 -3
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -271,7 +271,7 @@ public abstract class AbstractVarnodeEvaluator<T> implements VarnodeEvaluator<T>
* This is only invoked when trying to evaluate a leaf, which should never occur for a unique
* variable. Thus, by default, this throws a {@link PcodeExecutionException}.
*
* @param long the offset of the variable
* @param offset the offset of the variable
* @param size the size of the variable in bytes
* @return the value
*/
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/pcode/eval/VarnodeEvaluator.java
+3 -3
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -46,7 +46,7 @@ public interface VarnodeEvaluator<T> {
* Evaluate variable storage
*
* <p>
* Each varnode is evaluated as in {@link #evaluateStorage(VariableStorage)} and then
* Each varnode is evaluated as in {@link #evaluateStorage(Program, VariableStorage)} and then
* concatenated. The lower-indexed varnodes in storage are the more significant pieces, similar
* to big endian.
*
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBAnnotatedObject.java
+10 -10
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -34,12 +34,12 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
* fields from the record. These objects are managed using a {@link DBCachedObjectStore}. An example
* object definition:
*
* <pre>
* <pre>{@code
* interface Person {
* // ...
* }
*
* &#64;DBAnnotatedObjectInfo(version = 1)
* @DBAnnotatedObjectInfo(version = 1)
* public class DBPerson extends DBAnnotatedObject implements Person {
* public static final String TABLE_NAME = "Person"; // Conventionally defined here
*
@@ -48,15 +48,15 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
* static final String ADDRESS_COLUMN_NAME = "Address";
*
* // Column handles
* &#64;DBAnnotatedColumn(NAME_COLUMN_NAME)
* @DBAnnotatedColumn(NAME_COLUMN_NAME)
* static DBObjectColumn NAME_COLUMN;
* &#64;DBAnnotatedColumn(ADDRESS_COLUMN_NAME)
* @DBAnnotatedColumn(ADDRESS_COLUMN_NAME)
* static DBObjectColumn ADDRESS_COLUMN;
*
* // Column-backed fields
* &#64;DBAnnotatedField(column = NAME_COLUMN_NAME, indexed = true)
* @DBAnnotatedField(column = NAME_COLUMN_NAME, indexed = true)
* private String name;
* &#64;DBAnnotatedField(column = ADDRESS_COLUMN_NAME)
* @DBAnnotatedField(column = ADDRESS_COLUMN_NAME)
* private String address;
*
* DBPerson(DBCachedObjectStore<DBPerson> store, DBRecord record) {
@@ -72,7 +72,7 @@ import ghidra.util.database.annot.DBAnnotatedObjectInfo;
*
* // ... other methods, getters, setters
* }
* </pre>
* }</pre>
*
* <p>
* See {@link DBCachedObjectStoreFactory} for example code that uses the example {@code DBPerson}
@@ -192,7 +192,7 @@ public class DBAnnotatedObject extends DatabaseObject {
}
/**
* 2-arity version of {@link #update(DBObjectColumn...)}
* 3-arity version of {@link #update(DBObjectColumn...)}
*
* @param col1 a column
* @param col2 another column
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBCachedDomainObjectAdapter.java
+3 -3
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -162,7 +162,7 @@ public abstract class DBCachedDomainObjectAdapter extends DBDomainObjectSupport
protected ReadWriteLock rwLock;
/**
* @see {@link DBDomainObjectSupport}
* @see DBDomainObjectSupport
*/
protected DBCachedDomainObjectAdapter(DBHandle dbh, OpenMode openMode, TaskMonitor monitor,
String name, int timeInterval, int bufSize, Object consumer) {
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/DBCachedObjectStoreFactory.java
+15 -15
View File
@@ -41,7 +41,7 @@ import ghidra.util.exception.VersionException;
* See {@link DBAnnotatedObject} for more documentation, including an example object definition. To
* create a store, e.g., for {@code Person}:
*
* <pre>
* <pre>{@code
* interface MyDomainObject {
* Person createPerson(String name, String address);
*
@@ -71,7 +71,7 @@ import ghidra.util.exception.VersionException;
* }
* }
*
* &#64;Override
* @Override
* public Person createPerson(String name, String address) {
* // Locking details elided
* DBPerson person = people.create();
@@ -79,19 +79,19 @@ import ghidra.util.exception.VersionException;
* return person;
* }
*
* &#64;Override
* @Override
* public Person getPerson(int id) {
* // Locking details elided
* return people.getAt(id);
* }
*
* &#64;Override
* @Override
* public Collection<Person> getPeopleNamed(String name) {
* // Locking details elided
* return peopleByName.get(name);
* }
* }
* </pre>
* }</pre>
*
* <p>
* The factory manages tables on behalf of the domain object, so it is typically the first thing
@@ -159,7 +159,7 @@ public class DBCachedObjectStoreFactory {
* {@link DBAnnotatedObject} is sufficient. If context is required, then additional interfaces
* can be required via type intersection:
*
* <pre>
* <pre>{@code
* public interface MyContext {
* // ...
* }
@@ -175,14 +175,14 @@ public class DBCachedObjectStoreFactory {
* super(MyType.class, objectType, BinaryField.class, field, column);
* }
*
* &#64;Override
* @Override
* protected void doStore(OT obj, DBRecord record) {
* MyContext ctx = obj.getContext();
* // ...
* }
* // ...
* }
* </pre>
* }</pre>
*
* <p>
* Note that this implementation uses {@link AbstractDBFieldCodec}, which is highly recommended.
@@ -194,25 +194,25 @@ public class DBCachedObjectStoreFactory {
* {@link BinaryField}. See {@link ByteDBFieldCodec} for the simplest example with actual
* encoding and decoding implementations. To use the example codec in an object:
*
* <pre>
* &#64;DBAnnotatedObjectInfo(version = 1)
* <pre>{@code
* @DBAnnotatedObjectInfo(version = 1)
* public static class SomeObject extends DBAnnotatedObject implements ContextProvider {
* static final String MY_COLUMN_NAME = "My";
*
* &#64;DBAnnotatedColumn(MY_COLUMN_NAME)
* @DBAnnotatedColumn(MY_COLUMN_NAME)
* static DBObjectColumn MY_COLUMN;
*
* &#64;DBAnnotatedField(column = MY_COLUMN_NAME, codec = MyDBFieldCodec.class)
* @DBAnnotatedField(column = MY_COLUMN_NAME, codec = MyDBFieldCodec.class)
* private MyType my;
*
* // ...
*
* &#64;Override
* @Override
* public MyContext getContext() {
* // ...
* }
* }
* </pre>
* }</pre>
*
* <p>
* Notice that {@code SomeObject} must implement {@code ContextProvider}. This restriction is
@@ -406,7 +406,7 @@ public class DBCachedObjectStoreFactory {
throws IllegalArgumentException, IllegalAccessException;
/**
* Same as {@link #load(DBAnnotatedObject, DBRecord), but permits exceptions
* Same as {@link #load(DBAnnotatedObject, DBRecord)}, but permits exceptions
*/
protected abstract void doLoad(OT obj, DBRecord record)
throws IllegalArgumentException, IllegalAccessException;
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/spatial/AbstractConstraintsTree.java
-2
View File
@@ -119,7 +119,6 @@ public abstract class AbstractConstraintsTree< //
* {@link Collection#size()}. Filtering is performed by {@link TreeRecordVisitor}.
*
* @param parent the parent node
* @param query a query to control the ordering of the children
* @return a collection of the children
*/
protected Collection<DR> getDataChildrenOf(NR parent) {
@@ -137,7 +136,6 @@ public abstract class AbstractConstraintsTree< //
* {@link TreeRecordVisitor}.
*
* @param parent the parent node
* @param query a query to control the ordering of the children
* @return a collection of the children
*/
protected Collection<? extends DBTreeRecord<?, ? extends NS>> getChildrenOf(NR parent) {
Ghidra/Debug/ProposedUtils/src/main/java/ghidra/util/database/spatial/SpatialMap.java
+11 -8
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -113,12 +113,13 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/**
* Put an entry into the map
*
* <p>
* Note that the map may copy, and possibly modify, the given value. The value returned is the
* value actually stored by the map. This may be useful when the map's values are identical to
* its records. This allows the creation of a "blank" entry with a given shape. The entry is
* then populated by the user.
*
* <pre>
* <pre>{@code
* class MyDBDataRecord extends DBTreeDataRecord<MyShape, MyNodeShape, MyDBDataRecord> {
* &#64;Override
* protected void setValue(MyDBDataRecord value) {
@@ -129,18 +130,17 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
* return this; // The record is the value
* }
* }
* </pre>
*
* <pre>
* MyDBDataRecord rec = map.put(MyShape.create(args), null);
* rec.setSomething(6);
* rec.setAnother("My user data");
* </pre>
* }</pre>
*
* <p>
* This practice is preferred when the values are not simple, and/or when the shape is a
* property of the value. In other cases, e.g., when the value is an enum or a {@link Color},
* then {@link DBTreeDataRecord#setValue(Object)} and {@link DBTreeDataRecord#getValue()} should
* be implemented as field accessors.
* then {@link DBTreeDataRecord#setRecordValue(Object)} and
* {@link DBTreeDataRecord#getRecordValue()} should be implemented as field accessors.
*
* @param shape the shape of the entry
* @param value the value for the entry
@@ -151,6 +151,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/**
* Remove an entry from the map
*
* <p>
* Removes a single matching entry, if found, from the map. If you have a reference to an entry
* obtained from this map, use {@link #remove(Entry)} instead. Otherwise, this is the preferred
* method.
@@ -164,6 +165,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/**
* Remove an entry from the map
*
* <p>
* This method is preferred <em>only</em> when the given entry comes directly from this map.
* This spares the implementation from having to search for a matching entry. If the entry does
* not come from this map, it will behave like {@link #remove(BoundedShape, Object)}.
@@ -176,6 +178,7 @@ public interface SpatialMap<DS extends BoundedShape<?>, T, Q> {
/**
* Get or compute the size of this map
*
* <p>
* Note that this may not necessarily be a quick operation, esp., if this map is the result of
* {@link #reduce(Object)}. In the worst case, all elements in the reduced map will be visited.
*
Ghidra/Debug/ProposedUtils/src/main/java/utilities/util/SuppressableCallback.java
+7 -5
View File
@@ -4,9 +4,9 @@
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*
* http://www.apache.org/licenses/LICENSE-2.0
*
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -35,7 +35,7 @@ import java.util.function.*;
* A common use case is for a method to suppress any recursive calls, i.e., it is self suppressing,
* e.g.:
*
* <pre>
* <pre>{@code
* private final SuppressableCallback<Void> cbDoSomething = new SuppressableCallback<>();
*
* public boolean doSomething() {
@@ -51,7 +51,7 @@ import java.util.function.*;
* // do the other thing
* return doSomething();
* }
* </pre>
* }</pre>
*
* <p>
* This example is very trivial, but this sort of thing can easily happen in event driven
@@ -62,6 +62,8 @@ import java.util.function.*;
* resulting in unending oscillation between the requested states. A more robust solution demands we
* know the cause(s) of events. For now, the solution is to suppress event firing whenever a state
* change is due to receiving an event.
*
* @param <T> the type of return value, often {@link Void}
*/
public class SuppressableCallback<T> {
/**
@@ -193,7 +195,7 @@ public class SuppressableCallback<T> {
* The callback is always invoked, allowing it to decide what actions to take (or not take)
* based on the values present in the stack.
*
* @param callback
* @param callback a method to receive the stack
*/
public void invokeWithStack(Consumer<List<T>> callback) {
callback.accept(stack.get().view);