1. improve javadoc. 2. update javadoc

Former-commit-id: 550141a7bc62258281c0537a8cf3b57ee32e8cbe
Former-commit-id: 4183f43

SwerveRoboticsLibrary/doc/javadoc/index-all.html

@@ -718,7 +718,7 @@ <h2 class="title">I</h2>
 <dd>&nbsp;</dd>
 <dt><span class="memberNameLink"><a href="org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html#isOkToRead--">isOkToRead()</a></span> - Method in class <a href="org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html" title="class in org.swerverobotics.library.interfaces">II2cDeviceClient.ReadWindow</a></dt>
 <dd>
-<div class="block">Answers as to whether we're allowed to read using this window</div>
+<div class="block">Answers as to whether we're allowed to read using this window.</div>
 </dd>
 <dt><span class="memberNameLink"><a href="org/swerverobotics/library/SynchronousOpMode.html#isStarted--">isStarted()</a></span> - Method in class <a href="org/swerverobotics/library/SynchronousOpMode.html" title="class in org.swerverobotics.library">SynchronousOpMode</a></dt>
 <dd>

SwerveRoboticsLibrary/doc/javadoc/org/swerverobotics/library/interfaces/Autonomous.html

@@ -186,6 +186,10 @@ <h4>group</h4>
 <div class="block">Optionally indicates a group of other OpModes with which the annotated
  OpMode should be sorted on the driver station OpMode list.</div>
 <dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the group into which the annotated OpMode is to be categorized</dd>
+</dl>
+<dl>
 <dt>Default:</dt>
 <dd>""</dd>
 </dl>

SwerveRoboticsLibrary/doc/javadoc/org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html

@@ -235,7 +235,7 @@ <h3>Method Summary</h3>
 <tr id="i9" class="rowColor">
 <td class="colFirst"><code>boolean</code></td>
 <td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html#isOkToRead--">isOkToRead</a></span>()</code>
-<div class="block">Answers as to whether we're allowed to read using this window</div>
+<div class="block">Answers as to whether we're allowed to read using this window.</div>
 </td>
 </tr>
 <tr id="i10" class="altColor">
@@ -325,6 +325,10 @@ <h3>Method Detail</h3>
 <h4>getIregFirst</h4>
 <pre>public&nbsp;int&nbsp;getIregFirst()</pre>
 <div class="block">Returns the first register in the window</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the first register in the window</dd>
+</dl>
 </li>
 </ul>
 <a name="getIregMax--">
@@ -335,6 +339,10 @@ <h4>getIregFirst</h4>
 <h4>getIregMax</h4>
 <pre>public&nbsp;int&nbsp;getIregMax()</pre>
 <div class="block">Returns the first register NOT in the window</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the first register NOT in the window</dd>
+</dl>
 </li>
 </ul>
 <a name="getCreg--">
@@ -345,6 +353,10 @@ <h4>getIregMax</h4>
 <h4>getCreg</h4>
 <pre>public&nbsp;int&nbsp;getCreg()</pre>
 <div class="block">Returns the number of registers in the window</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the number of registers in the window</dd>
+</dl>
 </li>
 </ul>
 <a name="getReadMode--">
@@ -355,6 +367,10 @@ <h4>getCreg</h4>
 <h4>getReadMode</h4>
 <pre>public&nbsp;<a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.READ_MODE.html" title="enum in org.swerverobotics.library.interfaces">II2cDeviceClient.READ_MODE</a>&nbsp;getReadMode()</pre>
 <div class="block">Returns the mode of the window</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the mode of the window</dd>
+</dl>
 </li>
 </ul>
 <a name="getReadIssued--">
@@ -365,6 +381,10 @@ <h4>getReadMode</h4>
 <h4>getReadIssued</h4>
 <pre>public&nbsp;boolean&nbsp;getReadIssued()</pre>
 <div class="block">Returns whether a read has ever been issued for this window or not</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>whether a read has ever been issued for this window or not</dd>
+</dl>
 </li>
 </ul>
 <a name="setReadIssued--">
@@ -384,7 +404,12 @@ <h4>setReadIssued</h4>
 <li class="blockList">
 <h4>isOkToRead</h4>
 <pre>public&nbsp;boolean&nbsp;isOkToRead()</pre>
-<div class="block">Answers as to whether we're allowed to read using this window</div>
+<div class="block">Answers as to whether we're allowed to read using this window. This will return
+ false for ONLY_ONCE windows after <a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html#setReadIssued--"><code>setReadIssued()</code></a> has been called on them.</div>
+<dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>whether it is permitted to perform a read for this window.</dd>
+</dl>
 </li>
 </ul>
 <a name="freshCopy--">
@@ -406,6 +431,12 @@ <h4>sameAsIncludingMode</h4>
 <pre>public&nbsp;boolean&nbsp;sameAsIncludingMode(<a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.ReadWindow.html" title="class in org.swerverobotics.library.interfaces">II2cDeviceClient.ReadWindow</a>&nbsp;him)</pre>
 <div class="block">Do the receiver and the indicated register window cover exactly the
  same set of registers and have the same modality?</div>
+<dl>
+<dt><span class="paramLabel">Parameters:</span></dt>
+<dd><code>him</code> - the other window to compare to</dd>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the result of the comparison</dd>
+</dl>
 </li>
 </ul>
 <a name="contains-org.swerverobotics.library.interfaces.II2cDeviceClient.ReadWindow-">

SwerveRoboticsLibrary/doc/javadoc/org/swerverobotics/library/interfaces/TeleOp.html

@@ -185,6 +185,10 @@ <h4>group</h4>
 <div class="block">Optionally indicates a group of other OpModes with which the annotated
  OpMode should be sorted on the driver station OpMode list.</div>
 <dl>
+<dt><span class="returnLabel">Returns:</span></dt>
+<dd>the group into which the annotated OpMode is to be categorized</dd>
+</dl>
+<dl>
 <dt>Default:</dt>
 <dd>""</dd>
 </dl>

SwerveRoboticsLibrary/doc/javadoc/org/swerverobotics/library/interfaces/package-tree.html

@@ -117,24 +117,24 @@ <h2 title="Interface Hierarchy">Interface Hierarchy</h2>
 <h2 title="Annotation Type Hierarchy">Annotation Type Hierarchy</h2>
 <ul>
 <li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/Autonomous.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">Autonomous</span></a> (implements java.lang.annotation.Annotation)</li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/Disabled.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">Disabled</span></a> (implements java.lang.annotation.Annotation)</li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/OpModeRegistrar.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">OpModeRegistrar</span></a> (implements java.lang.annotation.Annotation)</li>
 <li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/TeleOp.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">TeleOp</span></a> (implements java.lang.annotation.Annotation)</li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/OpModeRegistrar.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">OpModeRegistrar</span></a> (implements java.lang.annotation.Annotation)</li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/Disabled.html" title="annotation in org.swerverobotics.library.interfaces"><span class="typeNameLink">Disabled</span></a> (implements java.lang.annotation.Annotation)</li>
 </ul>
 <h2 title="Enum Hierarchy">Enum Hierarchy</h2>
 <ul>
 <li type="circle">java.lang.Object
 <ul>
 <li type="circle">java.lang.Enum&lt;E&gt; (implements java.lang.Comparable&lt;T&gt;, java.io.Serializable)
 <ul>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.REGISTER.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.REGISTER</span></a></li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.ANGLEUNIT.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.ANGLEUNIT</span></a></li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.PITCHMODE.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.PITCHMODE</span></a></li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.READ_MODE.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">II2cDeviceClient.READ_MODE</span></a></li>
 <li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.I2CADDR.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.I2CADDR</span></a></li>
-<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.ACCELUNIT.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.ACCELUNIT</span></a></li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.REGISTER.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.REGISTER</span></a></li>
 <li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.SENSOR_MODE.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.SENSOR_MODE</span></a></li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.ACCELUNIT.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.ACCELUNIT</span></a></li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/II2cDeviceClient.READ_MODE.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">II2cDeviceClient.READ_MODE</span></a></li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.ANGLEUNIT.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.ANGLEUNIT</span></a></li>
 <li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.TEMPUNIT.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.TEMPUNIT</span></a></li>
+<li type="circle"><a href="../../../../org/swerverobotics/library/interfaces/IBNO055IMU.PITCHMODE.html" title="enum in org.swerverobotics.library.interfaces"><span class="typeNameLink">IBNO055IMU.PITCHMODE</span></a></li>
 </ul>
 </li>
 </ul>

SwerveRoboticsLibrary/doc/javadoc/org/usfirst/ftc/exampleteam/yourcodehere/MyOpModeRegistrar.html

@@ -116,27 +116,28 @@ <h2 title="Class MyOpModeRegistrar" class="title">Class MyOpModeRegistrar</h2>
  here, it is preferable to annotate them in their own source with <a href="../../../../../org/swerverobotics/library/interfaces/TeleOp.html" title="annotation in org.swerverobotics.library.interfaces"><code>TeleOp</code></a>
  or <a href="../../../../../org/swerverobotics/library/interfaces/Autonomous.html" title="annotation in org.swerverobotics.library.interfaces"><code>Autonomous</code></a> annotations, as appropriate.
 
- <p>NOTE: To make this work, for the moment at least you need to add your library module
- 'YourCodeHere' to the 'build.gradle' file in the FtcRobotController library. That build.gradle
- (be aware: each Android Studio module has its own) is found in $PROJECT_DIR$\FtcRobotController\build.gradle,
- where $PROJECT_DIR$ is the directory which contains SwerveRoboticsLibrary and YourCodeHere in addition to
- FtcRobotController. In that 'build.gradle', make sure the 'dependencies' section has a line
- compile project(':YourCodeHere') in addition to compile project(':SwerveRoboticsLibrary')
- and other things.</p>
+ <p>NOTE: if you previously cloned YourCodeHere for your team and per the then-current
+ instructions edited FtcRobotController\build.gradle to mention your project, you should
+ now remove that: FtcRobotController\build.gradle should now always be the original, verbatim
+ version as currently found here. Then, in your own project's build.gradle make necessary
+ changes to match the now-current YourCodeHere\build.gradle. Specifically, ensure that:
+ <ol>
+     <li>it uses <code>apply plugin: 'com.android.<em>application</em>'</code> not <code>...android.<em>module</em>'</code></li>
+     <li>its <code>defaultConfig</code> section contains the following</li>
+         <ol>
+         <li>the verbatim line <code>applicationId 'com.qualcomm.ftcrobotcontroller'</code></li>
+         <li>a <code>versionCode</code> line with the version three or greater: <code>versionCode 3</code></li>
+         </ol>
+     <li>its <code>dependencies</code> section contains the line <code>compile project(':FtcRobotController')</code></li>
+ </ol></p>
 
- <p>For the YourCodeHere module specifically, this has already been done for you. If you
- create your own sibling modules, you'll have to do that for yourself. We hope in the future
- to obviate the need for this step.</p>
-
- <p>UPDATE: at the moment, this is slightly broken, in that you cannot here reference
- the OpModes in the FtcRobotController module written by FTC HQ. Until that is fixed (we're
- working on it), if you want to use any of those OpModes you'll have to go back to the old
- way of modifying FtcOpModeRegister.register() directly. We apologize for the inconvenience.</p></div>
+ <p>If you're new to us here, these updates have already been done for you.</p></div>
 <dl>
 <dt><span class="seeLabel">See Also:</span></dt>
 <dd><a href="../../../../../org/swerverobotics/library/interfaces/TeleOp.html" title="annotation in org.swerverobotics.library.interfaces"><code>TeleOp</code></a>, 
 <a href="../../../../../org/swerverobotics/library/interfaces/Autonomous.html" title="annotation in org.swerverobotics.library.interfaces"><code>Autonomous</code></a>, 
-<a href="../../../../../org/swerverobotics/library/interfaces/OpModeRegistrar.html" title="annotation in org.swerverobotics.library.interfaces"><code>OpModeRegistrar</code></a></dd>
+<a href="../../../../../org/swerverobotics/library/interfaces/OpModeRegistrar.html" title="annotation in org.swerverobotics.library.interfaces"><code>OpModeRegistrar</code></a>, 
+<a href="../../../../../org/swerverobotics/library/examples/SynchTeleOp.html" title="class in org.swerverobotics.library.examples"><code>SynchTeleOp</code></a></dd>
 </dl>
 </li>
 </ul>

SwerveRoboticsLibrary/src/main/java/org/swerverobotics/library/interfaces/Autonomous.java

@@ -30,6 +30,7 @@
     /**
      * Optionally indicates a group of other OpModes with which the annotated
      * OpMode should be sorted on the driver station OpMode list.
+     * @return the group into which the annotated OpMode is to be categorized
      */
     String group() default "";
     }

SwerveRoboticsLibrary/src/main/java/org/swerverobotics/library/interfaces/II2cDeviceClient.java

@@ -389,22 +389,27 @@ class ReadWindow
 
         /**
          * Returns the first register in the window
+         * @return the first register in the window
          */
         public int getIregFirst() { return this.iregFirst; }
         /**
          * Returns the first register NOT in the window
+         * @return the first register NOT in the window
          */
         public int getIregMax()   { return this.iregFirst + this.creg; }
         /**
          * Returns the number of registers in the window
+         * @return the number of registers in the window
          */
         public int getCreg()      { return this.creg; }
         /**
          * Returns the mode of the window
+         * @return the mode of the window
          */
         public READ_MODE getReadMode() { return this.readMode; }
         /**
          * Returns whether a read has ever been issued for this window or not
+         * @return whether a read has ever been issued for this window or not
          */
         public boolean getReadIssued() { return this.readIssued; }
         /**
@@ -413,7 +418,9 @@ class ReadWindow
         public void setReadIssued() { this.readIssued = true; }
 
         /**
-         * Answers as to whether we're allowed to read using this window
+         * Answers as to whether we're allowed to read using this window. This will return
+         * false for ONLY_ONCE windows after {@link #setReadIssued()} has been called on them.
+         * @return whether it is permitted to perform a read for this window.
          */
         public boolean isOkToRead() { return this.readMode==READ_MODE.REPEAT || !this.readIssued; }
 
@@ -449,6 +456,8 @@ public ReadWindow freshCopy()
         /**
          * Do the receiver and the indicated register window cover exactly the
          * same set of registers and have the same modality?
+         * @param him   the other window to compare to
+         * @return the result of the comparison
          */
         public boolean sameAsIncludingMode(ReadWindow him)
             {

SwerveRoboticsLibrary/src/main/java/org/swerverobotics/library/interfaces/TeleOp.java

@@ -29,6 +29,7 @@
     /**
      * Optionally indicates a group of other OpModes with which the annotated
      * OpMode should be sorted on the driver station OpMode list.
+     * @return the group into which the annotated OpMode is to be categorized
      */
     String group() default "";
     }

YourCodeHere/build.gradle

@@ -5,11 +5,11 @@ android {
     buildToolsVersion "22.0.1"
 
     defaultConfig {
-        applicationId "com.qualcomm.ftcrobotcontroller"
+        applicationId 'com.qualcomm.ftcrobotcontroller'
         minSdkVersion 16
         targetSdkVersion 19
-        versionCode 3       // http://developer.android.com/tools/publishing/versioning.html
-        versionName "1.0"   // http://developer.android.com/tools/publishing/versioning.html
+        versionCode 3                       // http://developer.android.com/tools/publishing/versioning.html
+        versionName '@string/version_name'  // http://developer.android.com/tools/publishing/versioning.html
     }
     buildTypes {
         release {

YourCodeHere/src/main/java/org/usfirst/ftc/exampleteam/yourcodehere/MyOpModeRegistrar.java

@@ -12,6 +12,23 @@
  * here, it is preferable to annotate them in their own source with {@link TeleOp}
  * or {@link Autonomous} annotations, as appropriate.
  *
+ * <p>NOTE: if you previously cloned YourCodeHere for your team and per the then-current
+ * instructions edited FtcRobotController\build.gradle to mention your project, you should
+ * now remove that: FtcRobotController\build.gradle should now always be the original, verbatim
+ * version as currently found here. Then, in your own project's build.gradle make necessary
+ * changes to match the now-current YourCodeHere\build.gradle. Specifically, ensure that:
+ * <ol>
+ *     <li>it uses <code>apply plugin: 'com.android.<em>application</em>'</code> not <code>...android.<em>module</em>'</code></li>
+ *     <li>its <code>defaultConfig</code> section contains the following</li>
+ *         <ol>
+ *         <li>the verbatim line <code>applicationId 'com.qualcomm.ftcrobotcontroller'</code></li>
+ *         <li>a <code>versionCode</code> line with the version three or greater: <code>versionCode 3</code></li>
+ *         </ol>
+ *     <li>its <code>dependencies</code> section contains the line <code>compile project(':FtcRobotController')</code></li>
+ * </ol></p>
+ *
+ * <p>If you're new to us here, these updates have already been done for you.</p>
+ *
  * @see TeleOp
  * @see Autonomous
  * @see OpModeRegistrar
@@ -29,8 +46,8 @@ public class MyOpModeRegistrar
     @OpModeRegistrar
     public static void Register(IOpModeManager manager)
         {
-        // As an example, we here register some examples from the Swerve library.
-        // You'll probably want to change that.
+        // As an example, we here register some examples from the Swerve library
+        // and one of the FTC HQ example opmodes. You'll probably want to change that.
 
         manager.register(SynchTeleOp.class);
         manager.register(SynchTelemetryOp.class);

YourCodeHere/src/main/res/values/strings.xml

@@ -1,3 +1,3 @@
 <resources>
-    <string name="app_name">YourCodeHere</string>
+    <string name="version_name">YourCodeHere Robot Controller App v1.0</string>
 </resources>