diff --git a/README.md b/README.md
index 6e645db7..924eb7d0 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,7 @@ a link to this page somewhere in the documentation/system about section.
a `SingleResourceBProgram` in the constructor, as the argument for the name is now interpreted as a resource name. You can use `setName` to set the program name later.
* :sparkles: Automatic event names include the name of the class and an index number.
* :bug: Fixed broken links in the documentation.
+* :arrow_up: Improved Javadocs.
### 2018-12-19
* :sparkles: There are two different hot cycle violation inspections: one inspects a hot loop at the b-thread level (default), and the other at the whole b-program level.
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/DfsTraversalNode.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/DfsTraversalNode.java
index 19072914..e2188306 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/DfsTraversalNode.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/DfsTraversalNode.java
@@ -23,12 +23,12 @@
public class DfsTraversalNode {
/**
- * Get the initial nod ofr a run of the passed {@code BPorgram}.
+ * Get the initial nod for a run of the passed {@code BPorgram}.
*
* @param bp The {@link BProgram} being verified.
* @param exSvc The executor service that will run the threads
* @return Initial node for the BProgram run
- * @throws Exception
+ * @throws Exception in case there's an error with the executed JavaScript code.
*/
public static DfsTraversalNode getInitialNode(BProgram bp, ExecutorService exSvc) throws Exception {
BProgramSyncSnapshot seed = bp.setup().start(exSvc);
@@ -78,11 +78,11 @@ public String toString() {
* Get a Node object for each possible state of the system after triggering
* the given event.
*
- * @param e
+ * @param e the selected event
* @param exSvc The executor service that will run the threads
* @return State of the BProgram after event {@code e} was selected while
* the program was at {@code this} node's state.
- * @throws InterruptedException
+ * @throws Exception In case there's an error running the JavaScript code.
*/
public DfsTraversalNode getNextNode(BEvent e, ExecutorService exSvc) throws Exception {
return new DfsTraversalNode(bp, BProgramSyncSnapshotCloner.clone(systemState).triggerEvent(e, exSvc, Collections.emptySet()), e);
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/Requirements.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/Requirements.java
index 9cafcd86..16747e78 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/Requirements.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/analysis/Requirements.java
@@ -31,7 +31,20 @@
public class Requirements {
/**
- * A requirement that detects deadlocks (as in, no selectable events).
+ * Creates a b-thread that causes a false assertion when an event with a
+ * given name is selected.
+ *
+ * Sample usage, adding a requirement that a {@code BEvent("crash")} is
+ * never selected:
+ *
+ *
+ * BProgram bprog = ...
+ * bprog.appendSource( Requirements.eventNotSelected("crash") );
+ *
+ *
+ *
+ * @param eventName The name of the selected event.
+ * @return Source code for the b-thread.
*/
public static final String eventNotSelected( String eventName ) {
return "bp.registerBThread('eventNotSelected-" + eventName + "', function(){ "
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/BProgramJsProxy.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/BProgramJsProxy.java
index e4dcd85d..460637e1 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/BProgramJsProxy.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/BProgramJsProxy.java
@@ -134,7 +134,7 @@ public void registerBThread(Function func) {
*
* @param value The value of the assertion. When {@code false}, the program is declared in invalid state.
* @param message Textual information about what caused the violation.
- * @throws FailedAssertionException
+ * @throws FailedAssertionException if {@code value} is false.
*/
public void ASSERT( boolean value, String message ) throws FailedAssertionException {
if ( ! value ) {
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/SyncStatementBuilder.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/SyncStatementBuilder.java
index 5c1a1741..05b47f09 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/SyncStatementBuilder.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/execution/jsproxy/SyncStatementBuilder.java
@@ -23,13 +23,14 @@
*/
package il.ac.bgu.cs.bp.bpjs.execution.jsproxy;
+import il.ac.bgu.cs.bp.bpjs.model.SyncStatement;
import org.mozilla.javascript.NativeObject;
/**
* A base class for gradually building {@link SyncStatement}s.
*
* Implementation detail: We're using abstract class rather than interface, to
- * allow for the {@link #synchronizationPoint(org.mozilla.javascript.NativeObject, boolean, java.lang.Object)}
+ * allow for the {@link #synchronizationPoint(org.mozilla.javascript.NativeObject, Boolean, java.lang.Object)}
* method to be package-private.
*
* @author michael
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgram.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgram.java
index 11172fda..5fe6a9fd 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgram.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgram.java
@@ -34,7 +34,7 @@
* {@link #setupProgramScope(org.mozilla.javascript.Scriptable)} method.
*
* For creating a BProgram that uses a single JavaScript file available in the
- * classpath, see {@link SingleResourceBProgram}. For creating them from a
+ * classpath, see {@link ResourceBProgram}. For creating them from a
* hard-coded string, see {@link StringBProgram}.
*
* @author michael
@@ -140,7 +140,7 @@ public BProgram(String aName, EventSelectionStrategy anEss) {
*
* @throws IllegalStateException if the code is appended after the bprogram
* started.
- * @param source
+ * @param source JavaScript source to be added at the end of the current source.
*/
public void appendSource(String source) {
if (started) {
@@ -161,7 +161,7 @@ public void appendSource(String source) {
*
* @throws IllegalStateException if the code is appended after the bprogram
* started.
- * @param source
+ * @param source JavaScript source to be added at the beginning of the current source.
*/
public void prependSource(String source) {
if (started) {
@@ -344,7 +344,7 @@ private void initProgramScope(Context cx) {
*
* @return The event, or {@code null} in case the daemon mode is turned off
* during the wait.
- * @throws InterruptedException
+ * @throws InterruptedException (blocking call, we have to do this)
*/
public BEvent takeExternalEvent() throws InterruptedException {
BEvent next = recentlyEnqueuedExternalEvents.take();
@@ -363,7 +363,7 @@ public BEvent takeExternalEvent() throws InterruptedException {
* When set to {@code false}, when no events are available for selection,
* the program terminates.
*
- * @param shouldWait
+ * @param shouldWait {@code true} causes the system to wait for external events. {@code false} causes it to not wait.
*/
public void setWaitForExternalEvents(boolean shouldWait) {
if (waitForExternalEvents && !shouldWait) {
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgramSyncSnapshot.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgramSyncSnapshot.java
index 3da5880e..49eec323 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgramSyncSnapshot.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgramSyncSnapshot.java
@@ -99,7 +99,7 @@ public BProgramSyncSnapshot copyWith( List updatedExternalEvents ) {
*
* @param exSvc the executor service that will advance the threads.
* @return A snapshot of the program at the first {@code bsync}.
- * @throws java.lang.InterruptedException
+ * @throws java.lang.InterruptedException (since it's a blocking call)
*/
public BProgramSyncSnapshot start( ExecutorService exSvc ) throws InterruptedException {
Set nextRound = new HashSet<>(threadSnapshots.size());
@@ -120,9 +120,9 @@ public BProgramSyncSnapshot start( ExecutorService exSvc ) throws InterruptedExc
* Runs the program from the snapshot, triggering the passed event.
* @param exSvc the executor service that will advance the threads.
* @param anEvent the event selected.
- * @param listeners
+ * @param listeners will be informed in case of b-thread interrupts
* @return A set of b-thread snapshots that should participate in the next cycle.
- * @throws InterruptedException
+ * @throws InterruptedException (since it's a blocking call)
*/
public BProgramSyncSnapshot triggerEvent(BEvent anEvent, ExecutorService exSvc, Iterable listeners) throws InterruptedException {
if (anEvent == null) throw new IllegalArgumentException("Cannot trigger a null event.");
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BThreadSyncSnapshot.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BThreadSyncSnapshot.java
index f5666ec5..6373dbaf 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BThreadSyncSnapshot.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/BThreadSyncSnapshot.java
@@ -70,12 +70,12 @@ public BThreadSyncSnapshot(String aName, Function anEntryPoint) {
* Fully detailed constructor. Mostly useful for getting objects out of
* serialized forms.
*
- * @param name
- * @param entryPoint
- * @param interruptHandler
- * @param scope
- * @param continuation
- * @param bSyncStatement
+ * @param name name of the b-thread
+ * @param entryPoint function where the b-thread starts
+ * @param interruptHandler function to handle interrupts (or {@code null}, mostly)
+ * @param scope default top-level scope for the b-thread
+ * @param continuation captured b-thread continuation
+ * @param bSyncStatement current statement of the b-thread
*/
public BThreadSyncSnapshot(String name, Function entryPoint, Function interruptHandler, Scriptable scope,
Object continuation, SyncStatement bSyncStatement) {
diff --git a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/eventselection/AbstractEventSelectionStrategy.java b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/eventselection/AbstractEventSelectionStrategy.java
index 76f6443c..ec677b46 100644
--- a/src/main/java/il/ac/bgu/cs/bp/bpjs/model/eventselection/AbstractEventSelectionStrategy.java
+++ b/src/main/java/il/ac/bgu/cs/bp/bpjs/model/eventselection/AbstractEventSelectionStrategy.java
@@ -65,9 +65,9 @@ public long getSeed() {
/**
* Randomly select an event from {@code selectableEvents}, or a non-blocked event from {@code externalEvents}, in case {@code selectableEvents} is empty.
*
- * @param statements Statements at the current {@code bsync}.
- * @param externalEvents
- * @param selectableEvents
+ * @param statements Statements at the current {@code bsync}.
+ * @param externalEvents List of events that are not requested by b-threads (at least, not directly).
+ * @param selectableEvents Set of events that can be selected.
* @return An optional event selection result.
*/
@Override