minor changes due to documentation review

INSTALL

@@ -1,35 +0,0 @@
-ns-3.0.1 snapshot release, March 2007
-
-1.  Tested platforms:
-
-- Windows XP 32-bit Cygwin
-
-- Linux Fedora Core 5 x86
-
-- OS X 10.4.7 or later with XCode 2.4 or later 
-
-2.  Prerequisites:
-
-- The SCons build system (http://www.scons.org) version 0.96.1 or later
-
-- gcc (version 3.4 or later)
-
-3.  Installing into your current directory:
-
-tar xvfz ns-3.0.1.tar.gz
-cd ns-3.0.1
-scons
-cd build-dir/dbg-shared/bin/
-./simple-p2p
-
-The above steps will run a simple program whose source is found in
-ns-3.0.1/examples/simple-p2p.cc
-Some minimal trace output is found in simple-p2p.tr.
-
-Note:  OS X users may need to set the following env. variable from
-the bin/ directory above:
-setenv DYLD_LIBRARY_PATH `pwd`/../lib
-
-4.  For more information, read
-ns-3.0.1-documentation.pdf
- 

README

@@ -1,9 +1,9 @@
 
-    The Network Simulator Version 3
+    The Network Simulator, Version 3
-    -------------------------------
+    --------------------------------
 
-Table of Content:
+Table of Contents:
------------------
+------------------
 
 1) An Open Source project
 2) An overview of the ns-3 project
@@ -16,7 +16,7 @@ Table of Content:
 1) An Open Source project
 -------------------------
 
-ns-3 is an Open Source project and we intend to make this
+ns-3 is an Open Source project.   We intend to make this
 project a successful collaborative project: we hope that 
 the missing pieces of the models we have not yet implemented
 will be contributed by the community in an open collaboration
@@ -25,11 +25,11 @@ process.
 Contributing to the ns-3 project is still a very informal
 process because that process depends heavily on the personality
 of the people involved, the amount of time they can invest
-and the type of model they want to work on.
+and the type of model they want to work on.  
 
 Despite this lack of a formal process, there are a number of 
 steps which naturally stem from the open-source roots of the
-project. These steps are described in doc/contributing.txt
+project.  These steps are described in doc/contributing.txt
 
 2) An overview of the ns-3 project
 ----------------------------------
@@ -42,8 +42,9 @@ number of very simple network simulation models:
   - point-to-point physical-layer links
   - OnOff traffic generator
 
-However, the framework is there to make adding new models as 
+Our focus to date has been on getting an overall software
-simple as possible:
+framework in place.  The framework is there to make adding 
+new models as simple as possible:
   - an extensive tracing system can be used to connect
     any number of arbitrary trace sources to any number
     of trace sinks. This tracing system is decoupled
@@ -65,7 +66,7 @@ simple as possible:
 
 The code for the framework and the default models provided
 by ns-3 is built as a set of libraries. User simulations
-are expected to be written as simple programs which make
+are expected to be written as simple programs that make
 use of these ns-3 libraries.
 
 To build the set of default libraries and the example
@@ -92,14 +93,14 @@ the following platforms:
   - gcc 3.3 and earlier
   - optimized builds on linux x86 gcc 4.0 
 
-Other platforms might or might not work: we welcome 
+Other platforms may or may not work: we welcome 
 patches to improve the portability of the code to these
 other platforms.
 
 4) Running ns-3
 ---------------
 
-On Recent Linux systems, once you have built ns-3, it 
+On recent Linux systems, once you have built ns-3, it 
 should be easy to run the sample programs with the
 following command:
 
@@ -112,7 +113,7 @@ cd build-dir/dbg-shared/bin
 
 That program should generate a simple-p2p.tr text 
 trace file and a set of simple-p2p-xx-xx.pcap binary
-pcap trace files.
+pcap trace files, which can be read by tcpdump.
 
 5) Getting access to the ns-3 documentation
 -------------------------------------------
@@ -166,4 +167,4 @@ familiar with it.
 If you have successfully installed mercurial, you can get
 a copy of the development version with the following
 command:
-"hg clone http://code.nsnam.org/ns-3-dev"
+"hg clone http://code.nsnam.org/ns-3-dev"

RELEASE_NOTES

@@ -1,9 +1,9 @@
 
 		ns-3 RELEASE NOTES
 
-This file contains ns-3  release notes (most recent releases first).
+This file contains ns-3 release notes (most recent releases first).
 
-Release 0.2 (2007/05/XX)
+Release 3.0.2 (2007/05/18)
 ========================
 
   - Implement a new memory management infrastructure based
@@ -15,7 +15,7 @@ Release 0.2 (2007/05/XX)
 
   - Add support for a BSD-style socket API for user applications
 
-Release 0.1 (2007/03/31)
+Release 3.0.1 (2007/03/31)
 ========================
 
   - First public release; not yet pre-alpha.

VERSION

@@ -1 +1 @@
-3.0.1
+3.0.2

doc/build-waf.txt

@@ -1,12 +1,17 @@
-WAF is an alternative build system, similar to SCons.  NS-3 now is
+The main ns-3 build system is SCons.  Read the file build.txt
-able to build with WAF, in parallel to SCons.
+for SCons instructions.
 
-Note: the WAF build scripts are experimental at this stage.
+Waf is an alternative build system, similar to SCons.  ns-3 now is
+able to build with Waf, in parallel to SCons.
 
+(http://www.freehackers.org/~tnagy/waf.html)
 
-=== Building with WAF ===
+Note: the Waf build scripts are experimental at this stage.
+Gustavo Carneiro (gjcarneiro@gmail.com) is the maintainer.
 
-To build NS-3 with waf type the commands:
+=== Building with Waf ===
+
+To build ns-3 with waf type the commands:
  1. ./waf configure [options]
  2. ./waf
 
@@ -30,7 +35,7 @@ Other waf usages include:
     Run code coverage analysis (assuming the project was configured
 with --enable-gcov)
 
-=== Extending NS-3 ===
+=== Extending ns-3 ===
 
 To add new modules:
   1. Create the module directory under src (or src/devices, or whatever);
@@ -38,7 +43,7 @@ To add new modules:
   3. Add a 'wscript' describing it;
   4. Add the module subdirectory name to the all_modules list in src/wscript.
 
-A module's wscript file is basically a regular WAF script.  A NS-3
+A module's wscript file is basically a regular Waf script.  A ns-3
 module is created as a cpp/shlib object, like this:
 
 def build(bld):
@@ -65,7 +70,7 @@ def build(bld):
 
 === Note for developers ===
 
-The NS-3 code repository does not contain the waf script.  Instead,
+The ns-3 code repository does not contain the waf script.  Instead,
 developers should check it out from a subversion repository:
 
   svn checkout http://waf.googlecode.com/svn/tags/ns3/ waf
@@ -77,8 +82,8 @@ tested to work correctly with ns3, although 'trunk' will likely work
 Then it can be installed system-wide with 'sudo ./waf-light install'.
 When preparing a distribution, the resulting 'waf' script, which is
 self contained (no external files needed), can be easily included in
-the tarball so that users downloading NS-3 can easily build it without
+the tarball so that users downloading ns-3 can easily build it without
-having WAF installed (although Python >= 2.3 is still needed).
+having Waf installed (although Python >= 2.3 is still needed).
 
 The command 'waf dist' can be used to create a distribution tarball.
 It includes all files in the source directory, except some particular

doc/build.txt

@@ -16,6 +16,9 @@ the executable binaries generated link explicitely against
 the right libraries. This saves you the pain of having to
 setup environment variables to point to the right libraries.
 
+(Note:  An experimental, alternative build system is described
+in build-waf.txt)
+
 1) Options
 ----------
 

doc/codingstd.txt

@@ -0,0 +1,210 @@
+       The Ns-3 Coding Style
+
+/*
+ * Note:  This file is incomplete and will be converted to non-text (html,pdf)
+ * formats at a future date
+ */
+
+1) Code layout
+     -----------
+
+The code layout follows the GNU coding standard layout for C and extends
+it to C++. Do not use tabs for indentation. Indentation spacing is 2
+spaces as outlined below:
+
+void 
+Foo (void)
+{
+  if (test)
+    {
+      // do stuff here
+    }
+  else
+    {
+      // do other stuff here
+    }
+
+  for (int i = 0; i < 100; i++)
+    {
+      // do loop
+    }
+
+  while (test)
+    {
+      // do while
+    }
+
+  do
+    {
+      // do stuff
+    } while ();
+}
+
+The following is not recommended:
+
+if (test) statement
+
+if (test)
+  statement
+
+for (...) statement
+
+Each statement should be put on a separate line to increase readability.
+Short one-line comments can use the C++ comment style, that is, '//'
+but longer comments should use C-style comments:
+/*
+ *
+ *
+ */
+
+
+2) Naming Patterns
+   ---------------
+
+2.1) Name encoding
+     -------------
+Function, Method, and Type names should follow the CamelCase convention:
+words are joined without spaces and are capitalized. For example,
+"my computer" is transformed into MyComputer. Do not use all capital 
+letters such as MAC or, PHY, but choose instead Mac or Phy. Do not use
+all capital letters, even for acronyms such as EDCA: use Edca instead.
+The goal of the CamelCase convention is to ensure that the words which
+make up a name can be separated by the eye: the initial Caps fills
+that role.
+
+Variable names should follow a slight variation on the base CamelCase
+convention: camelBack. For example, the variable "user name" would be
+named "userName". This variation on the basic naming pattern is used to
+allow a reader to distinguish a variable name from its type. For example,
+"UserName userName;" would be used to declare a variable named userName
+of type UserName.
+
+Global variables should be prefixed with a "g_" and member variables
+(including static member variables) should be prefixed with a "m_". The
+goal of that prefix is to give a reader a sense of where a variable of
+a given name is declared to allow the reader to locate the variable 
+declaration and infer the variable type from that declaration. For example
+you could declare in your class header my-class.h:
+
+class MyClass
+{
+  void MyMethod (int aVar);
+  int m_aVar;
+  static int m_anotherVar;
+};
+
+and implement in your class file my-class.cc:
+
+int MyClass::m_anotherVar = 10;
+static int g_aStaticVar = 100;
+int g_aGlobalVar = 1000;
+
+void
+MyClass::MyMethod (int aVar)
+{
+  m_aVar = aVar;
+}
+
+2.2) Choosing names
+
+Variable, function, method, and type names should be based on the
+english language. Furthermore, always try to choose descriptive
+names for them. Types are often english names such as: Packet, 
+Buffer, Mac, or Phy. Functions and Methods are often named
+based on verbs and adjectives: GetX, DoDispose, ClearArray, etc.
+
+A long descriptive name which requires a lot of typing is always
+better than a short name which is hard to decipher. Do not use
+abbreviations in names unless the abbreviation is really unambiguous
+and obvious to everyone. Do not use short inapropriate names such
+as foo, bar, or baz. The name of an item should always match its 
+purpose. As such, names such as tmp to identify a temporary
+variable or such as 'i' to identify a loop index are ok.
+
+3) File layout and code organization
+   ---------------------------------
+
+A class named MyClass should be declared in a header named my-class.h
+and implemented in a source file named my-class.cc. The goal of this
+naming pattern is to allow a reader to quickly navigate through
+the ns-3 codebase to locate the source file relevant to a specific
+type.
+
+Each my-class.h header should start with the following comments: the
+first line ensures that developers who use the emacs editor will be 
+able to indent your code correctly. The following lines ensure that
+your code is licensed under the GPL, that the copyright holders
+are properly identified (typically, you or your employer), and
+that the actual author of the code is identified. The latter is
+purely informational and we use it to try to track the most
+appropriate person to review a patch or fix a bug.
+
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) YEAR COPYRIGHTHOLDER
+ * 
+ * 3-paragran GPL blurb
+ *
+ * Author: MyName <myemail@foo.com>
+ */
+
+Below these C-style comments, always include the following which
+defines a set of header guards (MY_CLASS_H) used to avoid multiple
+header includes, which ensures that your code is included
+in the "ns3" namespace and which provides a set of doxygen comments
+for the public part of your class API. Detailed information
+on the set of tags available for doxygen documentation is described
+in the doxygen website: http://www.doxygen.org.
+
+#ifndef MY_CLASS_H
+#define MY_CLASS_H
+
+namespace n3 {
+
+/**
+ * \brief short one-line description of the purpose of your class
+ *
+ * A longer description of the purpose of your class after a blank
+ * empty line.
+ */
+class MyClass
+{
+public:
+ MyClass ();
+ /**
+  * \param firstParam a short description of the purpose of this parameter
+  * \returns a short description of what is returned from this function.
+  *
+  * A detailed description of the purpose of the method.
+  */
+ int DoFoo (int firstParam);
+private:
+ void MyPrivateMethod (void);
+ int m_myPrivateMemberVariable;
+};
+
+} // namespace ns3
+
+#endif /* MY_CLASS_H */
+
+The my-class.cc file is structured similarly:
+
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) YEAR COPYRIGHTHOLDER
+ * 
+ * 3-paragran GPL blurb
+ *
+ * Author: MyName <myemail@foo.com>
+ */
+#include "my-class.h"
+
+namespace ns3 {
+
+MyClass::MyClass ()
+{}
+
+...
+
+} // namespace ns3
+

doc/contributing.txt

@@ -1,7 +1,13 @@
-
 Contributing to the ns-3 project
 --------------------------------
 
+ns-3 is an open source project backed by an NSF CISE CRI grant. 
+Although the NSF PIs have specific aims to fulfill, we want others to 
+contribute, and we'd like to have a broad community of users and 
+developers, with the goal of a self-sustaining project downstream. 
+The project is currently in a bootstrapping phase, but we welcome 
+ambitious developers who might want to help shape the early design.
+
 Despite the lack of a formal contribution process to the ns-3
 project, there are a number of steps which we expect every
 potential contributor to follow. These naturally stem from 
@@ -46,8 +52,12 @@ the open-source roots of the project:
     also expect model authors to act as responsible maintainers
     and be reactive to bug reports concerning their models.
 
-  - you should make sure that you understand that contributed
+  - The project has decided upon GNU GPLv2 as the licensing structure. 
-    models should be licensed under the GPLv2. You do not have
+    All simulation software in the ns-3 repositories will be GNU GPLv2 
-    to assign your copyright to the ns-3 project but you must
+    or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for
-    accept the terms of the GPLv2. See the following link:
+    ports of pre-existing code under a different license, such as BSD).
+    You do not have to assign your copyright to the ns-3 project but
+    you must accept the terms of the GPLv2 and attest that your 
+    contributions can be licensed under those terms.  See the 
+    following link:
     http://www.fsf.org/licensing/licenses/info/GPLv2.html

doc/mercurial.txt

@@ -3,7 +3,7 @@ Introduction
 
 ns-3 uses the Mercurial software revision control system which
 is a replacement for tools liks cvs or subversion. Thus, to get
-access to the developement versions of ns-3, you need to install
+access to the development versions of ns-3, you need to install
 mercurial first. See http://www.selenic.com/mercurial/wiki/
 
 Mercurial cheat sheet
@@ -38,6 +38,7 @@ push upwards (developers access only):
 --------------------------------------
 To the main repository:
 hg push ssh://code@code.nsnam.org/repos/ns-3-dev
+
 To your private repository:
 hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository