Updating documentation
diff --git a/docs/source/applications.rst b/docs/source/applications.rst
new file mode 100644
index 0000000..9fe1f5e
--- /dev/null
+++ b/docs/source/applications.rst
@@ -0,0 +1,136 @@
+ndnSIM applications
+===================
+
+ndnSIM includes a few reference applications that can be used as a base for NDN simulations.
+
+Reference applications
+++++++++++++++++++++++
+
+CcnxConsumerCbr
+^^^^^^^^^^^^^^^
+
+:ndnsim:`CcnxConsumerCbr` an application that generates Interest traffic with predefined pattern (constant frequency, constant average rate with inter-Interest gap distributed uniformly at random, exponentially at random, etc.).
+
+.. code-block:: c++
+
+ // Create application using the app helper
+ CcnxAppHelper helper ("ns3::CcnxConsumerCbr");
+
+This applications has the following attributes:
+
+* Frequency
+
+ .. note::
+ default: ``1.0`` (1 per second)
+
+ Either exact (for contant version) or expected (for randomized version) frequency with which Interests are generated
+
+ .. code-block:: c++
+
+ // Set attribute using the app helper
+ helper.SetAttribute ("Frequency", DoubleValue (1.0));
+
+* Randomize
+
+ .. note::
+ default: ``"none"``
+
+ Specify whether to do randomization for inter-Interest gap or not. The following variants are currently supported:
+
+ - ``"none"``: no randomization
+
+ - ``"uniform"``: uniform distribution in range (0, 1/Frequency)
+
+ - ``"exponential"``: exponential distribution with mean 1/Frequency
+
+ .. code-block:: c++
+
+ // Set attribute using the app helper
+ helper.SetAttribute ("Randomize", StringValue ("uniform"));
+
+CcnxConsumerBatches
+^^^^^^^^^^^^^^^^^^^
+
+:ndnsim:`CcnxConsumerBatches` is an on-off-style application gen- erating a specified number of Interests at specified points of simulation.
+
+.. code-block:: c++
+
+ // Create application using the app helper
+ CcnxAppHelper consumerHelper ("ns3::CcnxConsumerBatches");
+
+This applications has the following attributes:
+
+* Batches
+
+ .. note::
+ default: Empty
+
+ Specify exact pattern of Interest packets, specifying when and how many Interest packets should be sent.
+ The following example defines that 1 Interest should be requested at time 1s, 5 Interests at time 5s, and 2 Interests at time 10s.:
+
+ .. code-block:: c++
+
+ // Set attribute using the app helper
+ helper.SetAttribute ("Batches", StringValue ("1s 1 2s 5 10s 2"));
+
+
+CcnxConsumerWindow
+^^^^^^^^^^^^^^^^^^
+
+:ndnsim:`CcnxConsumerWindow` is an application generating a variable rate Interest traffic. It relies on an optional NACK-Interest feature and implements a simple sliding-window-based Interest generation mecha- nism.
+
+.. code-block:: c++
+
+ // Create application using the app helper
+ CcnxAppHelper consumerHelper ("ns3::CcnxConsumerWindow");
+
+
+This applications has the following attributes:
+
+* Window
+
+ .. note::
+ default: ``1``
+
+ Initial number of Interests that will be send out without waiting for the data (number of outstanding Interests)
+
+* PayloadSize
+
+ .. note::
+ default: ``1040``
+
+ Expected size of the Data payload (necessary only when Size is specified)
+
+* Size
+
+ .. note::
+ default: ``-1``
+
+ Amount of data to be requested (will stop issuing Interests after ``Size`` data is received)
+
+ If ```Size`` is set to -1, Interests will be requested till the end of the simulation.
+
+CcnxProducer
+^^^^^^^^^^^^
+
+:ndnsim:`CcnxProducer` a simple Interest-sink application, which replying every incoming Interest with Data packet with a specified size and name same as in Interest.
+
+.. code-block:: c++
+
+ // Create application using the app helper
+ CcnxAppHelper consumerHelper ("ns3::CcnxProducer");
+
+
+Custom applications
++++++++++++++++++++
+
+Applications interact with the core of the system using AppFace realization of Face abstraction.
+To simplify implementation of specific NDN application, ndnSIM provides a base CcnxApp class that takes care of creating CcnxAppFace and registering it inside the NDN protocol stack, as well as provides default processing for incoming Interest and Data packets.
+
+Base CcnxApp class
+^^^^^^^^^^^^^^^^^^
+
+
+
+Example
+^^^^^^^
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8da1d3a..54b990e 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -25,7 +25,7 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = [ "sphinx.ext.autodoc", "sphinxcontrib.doxylink" ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -240,3 +240,8 @@
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
+
+doxylink = {
+ 'ndnsim' : ('ndnSIM.tag', '../../doxygen/html/'),
+}
+
diff --git a/docs/source/helpers.rst b/docs/source/helpers.rst
new file mode 100644
index 0000000..51a3b16
--- /dev/null
+++ b/docs/source/helpers.rst
@@ -0,0 +1,173 @@
+ndnSIM helpers
+==============
+
+Helpers are very important components of ndnSIM, especially for writing simulation scenarios.
+The following summarizes helpers and their basic usage.
+
+CcnxStackHelper
+---------------
+
+:ndnsim:`CcnxStackHelper` is used to install ndnSIM network stack on requested nodes, as well to provide a simple way configure several important parameters of NDN simulation.
+
+Example::
+
+ CcnxStackHelper ccnxHelper;
+ NodeContainer nodes;
+ ...
+ ccnxHelper.Install (nodes);
+
+Forwarding strategy
++++++++++++++++++++
+
+Forwarding strategy parameter **must** be set before installing stack on a node.
+
+ Currently, there are 2 implemented forwarding strategies that can be used in simulations:
+
+ - :ndnsim:`CcnxFloodingStrategy` (default)
+
+ Interests will be forwarded to all available faces available for a route (FIB entry).
+ If there are no available GREEN or YELLOW faces, interests is dropped.
+
+ .. code-block:: c++
+
+ ccnxHelper.SetForwardingStrategy ("ns3::CcnxFloodingStrategy");
+ ...
+ ccnxHelper.Install (nodes);
+
+
+
+ - :ndnsim:`CcnxFloodingStrategy` with smart forwarding
+
+ If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
+ If not, Interest will be forwarded to all available faces available for a route (FIB entry)/
+ If there are no available GREEN or YELLOW faces, interests is dropped.
+
+ .. code-block:: c++
+
+ Config::SetDefault ("ns3::CcnxFloodingStrategy::SmartFlooding", BooleanValue (true));
+ ccnxHelper.SetForwardingStrategy ("ns3::CcnxFloodingStrategy");
+ ...
+ ccnxHelper.Install (nodes);
+
+ - :ndnsim:`CcnxBestRouteStrategy`
+
+ If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
+ If not, Interest will be forwarded to the highest-ranked YELLOW face.
+ If there are no available GREEN or YELLOW faces, interests is dropped.
+
+ .. code-block:: c++
+
+ ccnxHelper.SetForwardingStrategy ("ns3::CcnxBestRouteStrategy");
+ ...
+ ccnxHelper.Install (nodes);
+
+Default routes
+++++++++++++++
+
+.. note::
+ Disabled by default
+
+In simple topologies, like in :doc:`examples <examples>`, or when
+simulating broadcast environment, it is possible to set up *default*
+FIB entries using :ndnsim:`CcnxStackHelper::SetDefaultRoutes` call.
+More specifically, every installed NDN stack will have a FIB entry to ``/`` prefix, containing all available faces.
+
+The following should be done before installing stack on a node:
+
+ .. code-block:: c++
+
+ ccnxHelper.SetDefaultRoutes (true);
+ ...
+ ccnxHelper.Install (nodes);
+
+
+Manually routes
++++++++++++++++
+
+Routes can be configured manually using :ndnsim:`CcnxStackHelper::AddRoute` static methods of :ndnsim:`CcnxStackHelper`.
+
+These routes **should** be created **after** installing NDN stack on a node:
+
+ .. code-block:: c++
+
+ ccnxHelper.Install (nodes);
+ ...
+ Ptr<Node> node = ... // FIB entry will be added to FIB on this node
+ std::string prefix = ... // some prefix
+ Ptr<CcnxFace> face = ... // NDN face that belongs to the node and through which prefix is accessible
+ int32_t metric = ... // some routing metric
+ CcnxStackHelper::AddRoute (node, prefix, face, metric);
+
+
+.. Enable optional interest limiting
+.. +++++++++++++++++++++++++++++++++
+
+.. EnableLimits
+
+CcnxGlobalRoutingHelper
+-----------------------
+
+To simplify FIB management in large topologies, ndnSIM contains a global routing controller (:ndnsim:`helper <CcnxGlobalRoutingHelper>` and :ndnsim:`special interface <CcnxGlobalRouter>`), similar in spirit to ``Ipv4GlobalRoutingHelper``.
+
+There are several necessary steps, in order to take advantage of the global routing controller:
+
+* install :ndnsim:`special interfaces <CcnxGlobalRouter>` on nodes
+
+ .. code-block:: c++
+
+ NodeContainer nodes;
+ ...
+ CcnxGlobalRoutingHelper ccnxGlobalRoutingHelper;
+ ccnxGlobalRoutingHelper.Install (nodes);
+
+* specify which node exports which prefix using :ndnsim:`CcnxGlobalRoutingHelper::AddOrigins`
+
+ .. code-block:: c++
+
+ Ptr<Node> producer; // producer node that exports prefix
+ std::string prefix; // exported prefix
+ ...
+ ccnxGlobalRoutingHelper.AddOrigins (prefix, producer);
+
+* calculate and install FIBs on every node using :ndnsim:`CcnxGlobalRoutingHelper::CalculateRoutes`
+
+ .. code-block:: c++
+
+ ccnxGlobalRoutingHelper.CalculateRoutes ();
+
+
+CcnxAppHelper
+---------------
+
+:ndnsim:`CcnxAppHelper` simplifies task of creating, configuring, and installing ndnSIM applications.
+
+
+The basic usage of the :ndnsim:`CcnxAppHelper`:
+
+* Create helper for specific applications class:
+
+ .. code-block:: c++
+
+ // Create helper for the consumer generating Interests with constant rate
+ CcnxAppHelper consumerHelper ("ns3::CcnxConsumerCbr");
+
+* Assign prefix on which application operates (either generating Interests using this name or satisfying Interests for this name) using :ndnsim:`CcnxAppHelper::SetPrefix`:
+
+ .. code-block:: c++
+
+ consumerHelper.SetPrefix (prefix);
+
+* Assign application-specific attributes using :ndnsim:`CcnxAppHelper::SetAttribute`:
+
+ .. code-block:: c++
+
+ // Set frequency parameter
+ consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second
+
+* Install application on one or more nodes:
+
+ .. code-block:: c++
+
+ NodeContainer nodes;
+ ...
+ consumerHelper.Install (nodes)
diff --git a/docs/source/index.rst b/docs/source/index.rst
index ad6750f..db110f4 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,8 +6,9 @@
Contents:
.. toctree::
- :maxdepth: 2
+ :maxdepth: 4
intro
helpers
+ applications
examples
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index b4a03b5..0566861 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -123,7 +123,7 @@
Logging
-----------------
-Almost every component in ndnSIM exports logging interface, so it is possible in debug compilation of simulator to track many details. For example, by enabling logging of CcnxFace and CcnxConsumer will show everything what happens on CcnxFace and CcnxConsumer classes::
+Almost every component in ndnSIM exports logging interface, so it is possible in debug compilation of simulator to track many details. For example, by enabling logging of :ndnsim:`CcnxFace` and :ndnsim:`CcnxConsumer` will show everything what happens on :ndnsim:`CcnxFace` and :ndnsim:`CcnxConsumer` classes::
NS_LOG=CcnxFace:CcnxConsumer ./waf --run=ccnx-simple
@@ -134,7 +134,7 @@
Overall structure of ndnSIM is described in our technical report.
-It is also possible to build doxygen documentation of ndnSIM API (in ns-3/doc/html/), provided that doxygen and graphviz modules are installed on system::
+It is also possible to build doxygen documentation of ndnSIM API (in ``ns-3/doc/html/``), provided that ``doxygen`` and ``graphviz`` modules are installed on system::
./waf doxygen
@@ -142,23 +142,28 @@
A very short guide to the code
==============================
-All the NDN related code is in ns-3/src/ndnSIM
+All the NDN related code is in ``ns-3/src/ndnSIM``
+-----------------+---------------------------------------------------------------------+
| Folder | Description |
+=================+=====================================================================+
-| ``examples/`` | contain several example scenarios |
+| ``model/`` | implementation of NDN base: :ndnsim:`CcnxL3Protocol`, faces |
+| | (:ndnsim:`CcnxFace`, :ndnsim:`CcnxNetDeviceFace`, forwarding |
+| | :ndnsim:`CcnxLocalFace`), |
+| | strategies (:ndnsim:`CcnxForwardingStrategy`, |
+| | :ndnsim:`CcnxFloodingStrategy`, :ndnsim:`CcnxBestRouteStrategy`), |
+| | etc. |
+-----------------+---------------------------------------------------------------------+
| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
-| | Right now we have one producer (``CcnxProducer``) and a collection |
-| | of consumer (``CcnxConsumerCbr``, ``CcnxConsumerWindow``, |
-| | ``CcnxConsumerBatches``). See doxygen documentation or source |
-| | code for details |
+| | Right now we have one producer (:ndnsim:`CcnxProducer`) and a |
+| | collection of consumer (:ndnsim:`CcnxConsumerCbr`, |
+| | :ndnsim:`CcnxConsumerWindow`, |
+| | :ndnsim:`CcnxConsumerBatches`). See doxygen documentation or |
+| | source code for details |
+-----------------+---------------------------------------------------------------------+
-| ``helper/`` | a number of useful helpers |
+| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
+-----------------+---------------------------------------------------------------------+
-| ``model/`` | implementation of NDN base: L3 protocol, faces, forwarding |
-| | strategies, etc. |
+| ``examples/`` | contain :doc:`several example scenarios <examples>` |
+-----------------+---------------------------------------------------------------------+
| ``utils/`` | helper classes |
+-----------------+---------------------------------------------------------------------+