Javadoc fixes

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.

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);

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: 
+     * <code>
+     * 
+     * BProgram bprog = ...
+     * bprog.appendSource( Requirements.eventNotSelected("crash") );
+     * 
+     * </code>
+     * 
+     * @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(){ "

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 ) {

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

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) {

src/main/java/il/ac/bgu/cs/bp/bpjs/model/BProgramSyncSnapshot.java

@@ -99,7 +99,7 @@ public BProgramSyncSnapshot copyWith( List<BEvent> 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<BThreadSyncSnapshot> 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<BProgramRunnerListener> listeners) throws InterruptedException {
         if (anEvent == null) throw new IllegalArgumentException("Cannot trigger a null event.");

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) {

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