Difference between revisions of "Sprints"

From Nsnam
Jump to: navigation, search
(Upcoming sprints)
(Upcoming sprints: revise documentation instructions)
Line 14: Line 14:
 
= Upcoming sprints =
 
= Upcoming sprints =
  
* Friday October 3, 14h00-20h00 UTC ('''note:'''  attendees are welcome to attend a subset of the 6-hour slot, if so desired)
+
== Friday October 3, 14h00-20h00 UTC ==
** '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
+
('''note:'''  attendees are welcome to attend a subset of the 6-hour slot, if so desired)
** '''Topic:'''  Documentation improvement.  https://www.nsnam.org/bugzilla/show_bug.cgi?id=938.  In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen.  This is a long-standing issue that just requires group effort to resolve.
+
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
** '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
+
* '''Topic:'''  Documentation improvement.  https://www.nsnam.org/bugzilla/show_bug.cgi?id=938.  In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen.  This is a long-standing issue that just requires group effort to resolve.
** '''Preparation:'''
+
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
**# Read the general preparation below
+
* '''Preparation:'''
**# Make sure you have Doxygen installed on your system, and can run the shell script 'doc/doxygen.warnings.report.sh' (it may take a while to run, and should generate a lot of warnings).  
+
*# Read the general preparation below
**# Review this link about building doxygen, and filtering for output that you care about:  http://www.nsnam.org/docs/manual/html/documentation.html#building-doxygen-docs
+
*# Make sure you have Doxygen installed on your system, and can run the shell script <tt>doc/doxygen.warnings.report.sh</tt> (it may take a while to run, and should generate a lot of warnings).  
**# Review this link for ns-3 specific formatting:  http://www.nsnam.org/docs/manual/html/documentation.html#id1
+
*# Review this link about building doxygen, and filtering for output that you care about:  http://www.nsnam.org/docs/manual/html/documentation.html#building-doxygen-docs
**# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
+
*# Review this link for ns-3 specific formatting:  http://www.nsnam.org/docs/manual/html/documentation.html#id1
** '''Tasks:'''  Fix as many of the doxygen warnings as we can.  A current count of warnings (by module) can be seen here:  http://mailman.isi.edu/pipermail/ns-commits/2014-September/015625.html.  There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor.  How this is planned to work is that contributors who show up will be assigned a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
+
*# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
**  '''Coordination:'''  We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).
+
* '''Tasks:'''   
** '''How to build Doxygen for ns-3 and find the errors:'''
+
: Fix as many of the doxygen warnings as we can.  A current count of warnings (by module) can be seen here:  http://mailman.isi.edu/pipermail/ns-commits/2014-September/015625.html.  There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor.  How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
 +
*  '''Coordination:'''  We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).
  
Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
 
  
You must also have [http://doxygen.org Doxygen] installed on your machine.
+
=== How to build Doxygen for ns-3 and find the errors ===
  
Once you have ns-3-dev/ directory, take these steps:
 
  
  ./waf configure --enable-examples --enable-tests
+
*  Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
  ./waf build
+
*  You must also have [http://doxygen.org Doxygen] installed on your machine.
  ./waf --doxygen
+
  
Then, run the script doc/doxygen.warnings.report.sh from the ns-3-dev directory:
+
Once you have an <tt>ns-3-dev/</tt> directory, take these steps:
  
  ./doc/doxygen.warnings.report.sh >& doxygen.out
+
    $ ./waf configure --enable-examples --enable-tests
 +
    $ ./waf build
  
This will produce a file "doxygen.out" with lots of summary statistics like:
+
Then, run the script <tt>doc/doxygen.warnings.report.sh</tt> from the <tt>ns-3-dev</tt> directory:
  
      8 src/mobility/model/constant-acceleration-mobility-model.h
+
  $ ./doc/doxygen.warnings.report.sh
      8 src/mobility/model/box.h
+
      8 src/mesh/model/dot11s/ie-dot11s-perr.h
+
  
Now, you can cd into doc/ and look at doxygen.warnings.log file to find the exact error:
+
This will produce lots of summary statistics like:
  
e.g.
 
  
    /home/user/ns-3-allinone/ns-3-dev/src/mesh/model/dot11s/ie-dot11s-peering-protocol.h:31: warning: Compound ns3::dot11s::IePeeringProtocol is not documented.
+
  Warnings by module/directory:
 +
    Count Directory  ----- ----------------------------------  3219 src/lte/model  1173 src/wimax/model   1066 src/core/model    646 src/lte/test    518 src/wifi/model    ... </nowiki>
  
Once you find the list of files and look at the possible errors to fix, feel free to join the chat and request to take a module or file and fix it, and we will list it on the [http://etherpad.osuosl.org/gMofL8fupm Etherpad] as being taken.
+
Once this is complete, you can use the <tt>doxygen.warnings.report.sh</tt> script to focus on one module or file.  To see just the errors from one module, for example <tt>wifi</tt>:
 +
 
 +
 
 +
  $ ./doc/doxygen.warnings.report.sh -s -m wifi
 +
 
 +
 
 +
The <tt>-s</tt> option skips the doxygen run, and just reports results
 +
from the existing warnings log.  Obviously, if you want to see the results of your edits,
 +
you would omit the <tt>-s</tt> option.  The <tt>-m <module></tt> option only shows
 +
results from the <tt>./src/<module></tt> module; after printing the
 +
warnings counts by file, it shows the actual errors from each file:
 +
 
 +
  ...
 +
  Filtered Warnings
 +
  ========================================
 +
  src/wifi/examples/wifi-phy-test.cc:53: warning: Compound PsrExperiment::Output is not documented.
 +
  ...
 +
 
 +
 
 +
This means the type (probably a struct) <tt>PsrExperiment::Output</tt> has no documentation,
 +
and it's declared in <tt>src/wifi/examples/wifi-phy-test.cc</tt> around line 53.
 +
 
 +
 
 +
To see just the warnings from a single file (or a set of files matching a regular expression)
 +
use the <tt>-F <file-name-or-regex></tt> option: 
 +
 
 +
 
 +
  $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"
 +
 
 +
 
 +
=== How to add documentation during the sprint ===
 +
 
 +
 
 +
Once you find the list of files and look at the possible errors to fix, feel free to join the chat and request to take a module or file and fix it, and we will list it on the [http://etherpad.osuosl.org/gMofL8fupm Etherpad] as being taken. While all docs are valuable,
 +
we should probably focus on code in the model/ directories, then helpers/, examples/, and finally test/.
 +
 
 +
To add doxygen documentation, please follow the [http://www.nsnam.org/docs/manual/html/documentation.html#id1 ns-3 Specifics] guidelines.
 +
 
 +
Don't be surprised if you fix one warning and more appear!  If a struct, class or function
 +
has no documentation, doxygen reports a single "is not documented" error.  Once that object
 +
has documentation, then doxygen will examine it in detail and report additional warnings.
 +
For example, a function with no documentation will generate one warning.  Adding documentation
 +
''about the function itself'' will fix that warning, but then generate warnings for each of the
 +
function parameters and return value, until those are also documented.
 +
 
 +
Unfortunately, it's not enough just ''write'' documentation; you also have to test it.
 +
(Documentation has bugs too!)  Just rerun the <tt>doxygen.warnings.report.sh</tt> script without the <tt>-s</tt> option:
 +
 
 +
  $ ./doc/doxygen.warnings.report.sh -m <module> # or -F <file-name-or-regex>
 +
 
 +
(BTW, without <tt>-s</tt> the script will always build all the doxygen;
 +
the <tt>-m</tt> and <tt>-F</tt> options only
 +
affect what it displays from the resulting <tt>doxygen.warnings.log</tt>)
 +
 
 +
Once the script completes, load up the docs in your browser and check that it looks as you
 +
intended/you didn't mistype some doxygen syntax:
 +
 
 +
  $ firefox doc/html/index.html &
 +
 
 +
As in all code development:  wash, rinse, repeat, or, in this case:
 +
 
 +
  $ ./doc/doxygen.warnings.report.sh -m <module>
 +
  [edit, edit, edit]
 +
  $ firefox doc/html/index.html &
 +
 
 +
=== How to contribute your docs ===
  
 
Once you have fixed a file, you may create a patch such as follows:
 
Once you have fixed a file, you may create a patch such as follows:
  
   hg diff file-you-have-fixed.h > file-you-have-fixed.h.patch
+
   $ hg diff file-you-have-fixed.h > file-you-have-fixed.h.patch
  
and upload it to [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 bug 938] or email it to one of the maintainers participating in the script (you can ask on IRC about it).
+
and upload it to [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 bug 938] or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).
  
 
== General preparation ==
 
== General preparation ==

Revision as of 19:19, 26 September 2014

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

What is a sprint?

A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.

Sprints are open to anyone, and are conducted on IRC, and if needed, other virtual meeting technologies.

  • IRC channel is #ns-3 at irc.freenode.net

The Django project has a good reference and links to some presentations all about coding sprints.

A summary of the results of sprints will be shared with other developers on the ns-developers mailing list.

Upcoming sprints

Friday October 3, 14h00-20h00 UTC

(note: attendees are welcome to attend a subset of the 6-hour slot, if so desired)

Fix as many of the doxygen warnings as we can. A current count of warnings (by module) can be seen here: http://mailman.isi.edu/pipermail/ns-commits/2014-September/015625.html. There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor. How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
  • Coordination: We will use IRC and Etherpad to coordinate the work (make sure multiple people do not work on the same file).


How to build Doxygen for ns-3 and find the errors

  • Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
  • You must also have Doxygen installed on your machine.

Once you have an ns-3-dev/ directory, take these steps:

   $ ./waf configure --enable-examples --enable-tests
   $ ./waf build

Then, run the script doc/doxygen.warnings.report.sh from the ns-3-dev directory:

 $ ./doc/doxygen.warnings.report.sh

This will produce lots of summary statistics like:


 Warnings by module/directory:
   Count Directory  ----- ----------------------------------   3219 src/lte/model   1173 src/wimax/model   1066 src/core/model    646 src/lte/test    518 src/wifi/model    ... </nowiki>

Once this is complete, you can use the doxygen.warnings.report.sh script to focus on one module or file. To see just the errors from one module, for example wifi:


 $ ./doc/doxygen.warnings.report.sh -s -m wifi


The -s option skips the doxygen run, and just reports results from the existing warnings log. Obviously, if you want to see the results of your edits, you would omit the -s option. The -m <module> option only shows results from the ./src/<module> module; after printing the warnings counts by file, it shows the actual errors from each file:

 ...
 Filtered Warnings
 ========================================
 src/wifi/examples/wifi-phy-test.cc:53: warning: Compound PsrExperiment::Output is not documented.
 ...


This means the type (probably a struct) PsrExperiment::Output has no documentation, and it's declared in src/wifi/examples/wifi-phy-test.cc around line 53.


To see just the warnings from a single file (or a set of files matching a regular expression) use the -F <file-name-or-regex> option:


 $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"


How to add documentation during the sprint

Once you find the list of files and look at the possible errors to fix, feel free to join the chat and request to take a module or file and fix it, and we will list it on the Etherpad as being taken. While all docs are valuable, we should probably focus on code in the model/ directories, then helpers/, examples/, and finally test/.

To add doxygen documentation, please follow the ns-3 Specifics guidelines.

Don't be surprised if you fix one warning and more appear! If a struct, class or function has no documentation, doxygen reports a single "is not documented" error. Once that object has documentation, then doxygen will examine it in detail and report additional warnings. For example, a function with no documentation will generate one warning. Adding documentation about the function itself will fix that warning, but then generate warnings for each of the function parameters and return value, until those are also documented.

Unfortunately, it's not enough just write documentation; you also have to test it. (Documentation has bugs too!) Just rerun the doxygen.warnings.report.sh script without the -s option:

 $ ./doc/doxygen.warnings.report.sh -m <module> # or -F <file-name-or-regex>

(BTW, without -s the script will always build all the doxygen; the -m and -F options only affect what it displays from the resulting doxygen.warnings.log)

Once the script completes, load up the docs in your browser and check that it looks as you intended/you didn't mistype some doxygen syntax:

 $ firefox doc/html/index.html &

As in all code development: wash, rinse, repeat, or, in this case:

 $ ./doc/doxygen.warnings.report.sh -m <module>
 [edit, edit, edit]
 $ firefox doc/html/index.html &

How to contribute your docs

Once you have fixed a file, you may create a patch such as follows:

 $ hg diff file-you-have-fixed.h > file-you-have-fixed.h.patch

and upload it to bug 938 or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).

General preparation

  • Make sure that you can join the IRC channel in advance
  • Make sure you can checkout the development version of ns-3 (we will use ns-3-dev)
  • Familiarize yourself with how to generate a patch against ns-3-dev. Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.

Once you're there

  • Check in on IRC by letting others know that you've joined and are ready to contribute, and a maintainer will go from there