When proposing new models to |ns3|, please keep in mind that not all models
will be accepted into the mainline. However, we aim to provide at least
one or more options for any code contribution.
Because of the long-term maintenance burden, |ns3| is no longer accepting
all new proposals into the mainline. Features that are of general
interest are more likely to be approved for the mainline, but features that
are more specialized may be recommended for the `ns-3 App Store <https://apps.nsnam.org>`_. Some modules that have been in the mainline for a long time, but
fall out of use (or lose their maintainers) may also be moved out of the
mainline into the App Store in the future.
The options for publishing new models are:
1. Propose a Merge Request for the |ns3| mainline and follow the guidelines below.
If you add a new features, or make changes to existing features, you need to
update existing or write new documentation and example code. Consider the
following checklist:
* Doxygen should be added to header files for all public classes and methods, and should be checked for Doxygen errors
* New features should be described in the ``RELEASE_NOTES.md``
* Public API changes (if any) must be documented in ``CHANGES.md``
* New API or changes to existing API must update the inline Doxygen documentation in header files
* Consider updating or adding a new section to the manual (``doc/manual``) or
model library (``doc/models``) as appropriate
* Update the ``AUTHORS`` file for any new authors
Guidelines to Write Sphinx Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here are some general guidelines when creating Sphinx documentation:
* When possible, avoid using more than 2 levels of hierarchy (i.e., create only sections and subsections).
* Avoid creating sections or subsections that only contain small paragraphs. If the content is too short, consider combining the content of 2 sections/subsections into one (exceptions include the fixed sections and subsections).
* Include code snippets and/or images (figures or text-based) to better explain your content. This is particularly recommended for the helpers subsection.
* Use references with numbers, rather than using names. Include the reference link when available (use the number for the link).
* Follow the section hierarchy explained in this guide.
* Verify that there is a line between the header and the body of each section or subsection.
For a concrete example, see ``src/lr-wpan/doc/lr-wpan.rst``.
Documentation should be created using the following heading hierarchy:
::
Model Name
==========
Section
-------
Subsection
~~~~~~~~~~
SubsubSection (Use only in extreme cases!)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In general, the number of sections or subsection is free, but there are a few sections and subsections that must be present.
The following is the general outline of a module documentation in ns-3:
::
My fantastic model name here
============================
This first part is for describing what the model is trying to accomplish.
General descriptions , design, overview of the project goes in this part without the need of any subsections.
An additional visual summary is also recommended.
Scope and Limitations
---------------------
A list of missing capabilities or things not considered in the model goes here.
This section is fixed and must be the first section in the model documentation.
Section A
---------
Free form sections and subsections goes here.
Section B
---------
Free form sections and subsections goes here.
Usage
-----
A brief description of the model usage goes here. This section must be present.
Helpers
~~~~~~~
A description of the helpers used by the model goes here. Snippets of code are
preferable when describing the helpers usage. This subsection must be present.
If the model CANNOT provide helpers write "Not applicable".
Attributes
~~~~~~~~~~
A list of attributes used by the model, each attribute should include a small
description. This subsection must be present.
If the model CANNOT provide attributes write "Not applicable".
Traces
~~~~~~
A list of the source traces used by the model, each trace should include a small
description. This subsection must be present.
If the model CANNOT provide traces write "Not applicable".
Examples and Tests
------------------
Do not forget to add a brief description of each example and test present in the model.
Example:
``my-example.cc : This example demonstrate the use of x in y situation.``
This section must be present.
Validation
----------
Descriptions of how the model was validated must be here. This section must be present.
References
----------
The reference material used in the construction of the model. This section must be present.
For many submissions, it will be important to include at least one example that exercises the new code, so the reviewer understands how it is intended to be used. For final submission, please consider to add as many examples as you can that will help new users of your code. The ``samples/`` and ``examples/`` directories are places for these files.
