Update some stale documentation in doc/ directory
authorTom Henderson <tomh@tomh.org>
Wed, 29 Dec 2010 11:15:54 -0800
changeset 6736 fa6d53fb98a5
parent 6735 8fda47c85df2
child 6737 623189bc65be
Update some stale documentation in doc/ directory
doc/codingstd.txt
doc/contributing.txt
doc/modules
--- a/doc/codingstd.txt	Wed Dec 29 11:05:41 2010 -0800
+++ b/doc/codingstd.txt	Wed Dec 29 11:15:54 2010 -0800
@@ -1,210 +1,2 @@
-       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
-
+The project coding style document is maintained at:
+http://www.nsnam.org/codingstyle.html
--- a/doc/contributing.txt	Wed Dec 29 11:05:41 2010 -0800
+++ b/doc/contributing.txt	Wed Dec 29 11:15:54 2010 -0800
@@ -1,63 +1,7 @@
 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 
-the open-source roots of the project:
-
-  - first, you should subscribe to the ns-developers 
-    mailing-list (see http://www.nsnam.org/mailing_lists.html)
-
-  - then, you should send an email there stating your interest
-    in working on a specific part of the models and trying
-    to explain how you would like to implement it, what 
-    resources you have, etc.
-
-  - you should be prepared to work together with the other
-    potential contributors who want to work on the same models.
-
-  - you should be prepared to go through code reviews with the
-    ns-3 development team prior to integration. The goal of these
-    code reviews is to:
-      - ensure adherence to the coding style of the project
-        (see doc/codingstyle.html)
-      - ensure that the structure of your code has a certain 
-        coherence with regard to the rest of the ns-3 codebase
-      - improve the quality of the code: we strongly believe in
-        the old saying: "many eyes make all bugs shallow".
-      - increase code reuse by trying to generalize certain 
-        useful pieces of your code to make them available to
-        other models.
-
-  - you should be prepared to try to integrate as many tests
-    in the codebase as possible: we understand that writing
-    tests is not sexy and that not everyone is convinced that
-    they improve the code-writing poductivity which is why
-    we do not enforce strict rules about testing. However,
-    we expect model authors to answer basic questions about
-    how they plan to test and validate their models.
-
-  - you should be prepared to maintain your model once it is
-    integrated: while we consider every bug filed against the 
-    simulator as being a bug we must deal with and while we 
-    will try to fix as many bugs as humanly possible, we
-    also expect model authors to act as responsible maintainers
-    and be reactive to bug reports concerning their models.
-
-  - The project has decided upon GNU GPLv2 as the licensing structure. 
-    All simulation software in the ns-3 repositories will be GNU GPLv2 
-    or GNU GPLv2-compatible (with non-GPLv2 licensing reserved for
-    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
+ns-3 is a free, open source software project that welcomes contributions
+from users worldwide.  Please see the following web page for how to 
+contribute:  
+http://www.nsnam.org/contributing.html
--- a/doc/modules	Wed Dec 29 11:05:41 2010 -0800
+++ b/doc/modules	Wed Dec 29 11:15:54 2010 -0800
@@ -46,6 +46,7 @@
  * 
  * The "internet-stack" module contains:
  *    - an Ipv4 stack
+ *    - an Ipv6 stack
  *    - an ARP module
  *    - a UDP and a TCP implementation
  *