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.
- Friday October 3, 14h00-20h00 UTC (note: attendees are welcome to attend a subset of the 6-hour slot, if so desired)
- Etherpad: http://etherpad.osuosl.org/gMofL8fupm
- 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.
- Organizer: Tom Henderson
- Read the general preparation below
- 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).
- 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
- Review this link for ns-3 specific formatting: http://www.nsnam.org/docs/manual/html/documentation.html#id1
- Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
- 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.
- 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 ns-3-dev/ directory, take these steps:
./waf configure --enable-examples --enable-tests ./waf build ./waf --doxygen
Then, run the script doc/doxygen.warnings.report.sh from the ns-3-dev directory:
./doc/doxygen.warnings.report.sh >& doxygen.out
This will produce a file "doxygen.out" with lots of summary statistics like:
8 src/mobility/model/constant-acceleration-mobility-model.h 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:
/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.
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.
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 script (you can ask on IRC about it).
- 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