Bug 938 - missing Doxygen in ns-3
missing Doxygen in ns-3
Status: PATCH PENDING
Product: ns-3
Classification: Unclassified
Component: documentation
pre-release
All All
: P4 normal
Assigned To: Tom Henderson
:
: 766 (view as bug list)
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2010-06-07 00:40 EDT by Tom Henderson
Modified: 2017-08-21 16:06 EDT (History)
10 users (show)

See Also:


Attachments
list of missing doxygen (597.81 KB, text/plain)
2010-06-07 00:40 EDT, Tom Henderson
Details
Work-in-progress patch (331.15 KB, application/octet-stream)
2011-10-29 11:40 EDT, Vedran Miletić
Details
Doxygen fixes (updated patch) (338.24 KB, patch)
2011-10-29 15:42 EDT, Vedran Miletić
Details | Diff
Doxygen patch that fixes erros without style changes (63.17 KB, patch)
2011-11-04 13:07 EDT, Vedran Miletić
Details | Diff
Topology-reader docs fixing (6.97 KB, patch)
2011-11-04 16:41 EDT, Tommaso Pecorella
Details | Diff
Topology docs fixings (7.35 KB, patch)
2011-11-06 11:47 EST, Tommaso Pecorella
Details | Diff
MPI modules patch for Doxygen warnings (848 bytes, patch)
2013-11-15 10:37 EST, Jared Ivey
Details | Diff
current list of doxygen warnings to fix (61.21 KB, text/plain)
2013-11-15 10:46 EST, Tom Henderson
Details
the actual warnings (795.84 KB, text/plain)
2013-11-15 10:48 EST, Tom Henderson
Details
actual warnings (part 2) (788.00 KB, text/plain)
2013-11-15 10:49 EST, Tom Henderson
Details
Stats module patch for Doxygen warnings (20.65 KB, patch)
2013-11-15 16:04 EST, Jared Ivey
Details | Diff
Patch to partially fix doxygen warnings in wifi module (99.21 KB, patch)
2013-11-15 19:15 EST, Daniel L.
Details | Diff
Patch to fix some doxygen warnings in lte module (64.23 KB, patch)
2013-11-16 12:49 EST, Budiarto Herman
Details | Diff
Internet model fixes (224.36 KB, patch)
2013-11-19 16:44 EST, Tommaso Pecorella
Details | Diff
New Internet docs patch (229.56 KB, patch)
2013-11-21 05:05 EST, Tommaso Pecorella
Details | Diff
flow-monitor model + helper (25.00 KB, patch)
2013-11-21 14:38 EST, Tommaso Pecorella
Details | Diff
log of current doxygen warnings (88.50 KB, application/x-gzip)
2013-11-25 10:39 EST, Tom Henderson
Details
summary of current warnings report (47.04 KB, text/plain)
2013-11-25 10:40 EST, Tom Henderson
Details
summary of current warnings (47.04 KB, text/plain)
2013-11-25 10:42 EST, Tom Henderson
Details
A second patch to partially fix doxygen warnings in wifi module (120.87 KB, patch)
2013-11-26 12:01 EST, Daniel L.
Details | Diff
stats Doxygen fixes (35.52 KB, patch)
2013-12-14 11:10 EST, Tommaso Pecorella
Details | Diff
Network module fixes (159.10 KB, patch)
2014-03-02 17:02 EST, Tommaso Pecorella
Details | Diff
Point-to-point documentation patch (18.18 KB, patch)
2014-10-03 11:04 EDT, natale.patriciello
Details | Diff
Internet module fixes (6.16 KB, patch)
2014-10-03 11:16 EDT, Tommaso Pecorella
Details | Diff
mobility patch from Tiago (4.04 KB, patch)
2014-10-03 16:04 EDT, Tom Henderson
Details | Diff
propagation models patch (40.12 KB, patch)
2014-10-03 16:58 EDT, Tommaso Pecorella
Details | Diff
Patch to fix some doxygen warnings in lte module (91.86 KB, patch)
2014-10-05 16:28 EDT, Budiarto Herman
Details | Diff
Asn1 header docs from Tommaso (17.61 KB, application/octet-stream)
2014-10-06 13:38 EDT, Peter Barnes
Details
Sphinx docs for propagation module (21.89 KB, patch)
2015-03-01 05:36 EST, Tommaso Pecorella
Details | Diff
some small fixes (1.98 KB, patch)
2015-05-22 11:19 EDT, Tommaso Pecorella
Details | Diff
Internet module fixes (996 bytes, patch)
2015-05-23 18:25 EDT, Tommaso Pecorella
Details | Diff
Spectrum model stuff (65.11 KB, patch)
2015-05-25 05:12 EDT, Tommaso Pecorella
Details | Diff
updated patch for the Spectrum model (64.35 KB, patch)
2015-08-22 06:53 EDT, Tommaso Pecorella
Details | Diff
OLSR documentation update. (115.49 KB, patch)
2016-01-23 13:02 EST, Tommaso Pecorella
Details | Diff
OLSR uncrustified (65.71 KB, patch)
2016-01-23 13:04 EST, Tommaso Pecorella
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Tom Henderson 2010-06-07 00:40:06 EDT
Created attachment 914 [details]
list of missing doxygen

Attached file shows current state of missing Doxygen for ns-3.  We are proposing to block ns-3.9 until clearing this backlog of missing doxygen.

Also, we should revisit this doxygen.conf file which hasn't been touched for a while; the EXCLUDEs may be stale

EXCLUDE                = src/routing/olsr/olsr-state.h \
                         src/routing/olsr/olsr-repositories.h \
                         src/simulator/high-precision.h \
                         src/simulator/high-precision-128.h \
                         src/simulator/high-precision-double
Comment 1 Tom Henderson 2010-08-12 19:30:35 EDT
Thank you Pavel and others who have started this cleanup.  I decided not to block the release on this but we'd like to aim for full cleanup by ns-3.10.
Comment 2 Tom Henderson 2011-06-25 11:24:20 EDT
Update:  I would like to make progress on this as follows:

1) fix errors on a module-by-module basis, starting with core and working outward in the dependency tree.

Specifically, disable these two warnings in doxygen.conf about undocumented components and fix just the remaining errors:

-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO

-WARN_NO_PARAMDOC       = YES
+WARN_NO_PARAMDOC       = NO

2) once ns-3-dev is clean from step 1, start buildbot testing of doxygen in this modified configuration to prevent new errors.  Also start daily reporting of the count of undocumented components (i.e. with the two above flags enabled) so that we can track that the number does not grow (however, don't report a failed test for these undocumented items).

3) start working on undocumented components starting with module core and moving outward.  

I think that 1) and 2) are reasonable goals for the ns-3.12
Comment 3 Vedran Miletić 2011-09-03 04:50:06 EDT
Hi Tom, is there a patch on this already?

Back in June, some of my students and me have been working on cleaning ns-3 Doxygen documentation and made a lot of progress on 2). We have a work-in-progress patch that I will post here once it's fixed to apply cleanly to ns-3-dev. If there are no objections, I'm willing to take this bug.
Comment 4 Tom Henderson 2011-09-05 10:07:59 EDT
(In reply to comment #3)
> Hi Tom, is there a patch on this already?

No

> 
> Back in June, some of my students and me have been working on cleaning ns-3
> Doxygen documentation and made a lot of progress on 2). We have a
> work-in-progress patch that I will post here once it's fixed to apply cleanly
> to ns-3-dev. If there are no objections, I'm willing to take this bug.

That would be much appreciated.  Please don't hesitate to post partial fixes as well.
Comment 5 Vedran Miletić 2011-09-26 15:59:11 EDT
Hi Tom,

do we prefer \ to @ for doxygen commands, and
do we prefer /** */ format for long docs to multiple ///?

I have a student interested in helping with this; will revisit doxygen.conf msyself; patch soon.
Comment 6 Tom Henderson 2011-09-26 16:46:30 EDT
(In reply to comment #5)

This is addressed in the coding style document:
http://www.nsnam.org/developers/contributing-code/coding-style/#comments

> do we prefer \ to @ for doxygen commands, and

structural commands may start either with \ or @; both styles are found in the existing codebase.  

> do we prefer /** */ format for long docs to multiple ///?

Also for this question, it has also been done both ways, but I believe that the /** */ is found more than the /// style.

In general, since this is an effort to add missing doxygen, I would suggest to keep with prevailing style for each file.  Or, try to determine the prevailing style for the module as a whole (if there is one) and use that.

Note, if you have suggestions to make the coding style document more clear in this regard, feel free to suggest that too.
Comment 7 Vedran Miletić 2011-10-29 11:40:16 EDT
Created attachment 1265 [details]
Work-in-progress patch

As promised, I ported the work we did on this before summer to latest ns-3-dev. This fixes some doxgen errors we encountered back then, but undocumented stuff is mostly unchanged. Patch also replaces all @commands stuff with \command for consistency.

I plan to resolve all undefined references and references to functions that don't exist, as there aren't that many:

$ grep -v "not documented" doxygen.log | grep -v "not (all) documented" | wc -l
111

Some feedback is appreciated.
Comment 8 Vedran Miletić 2011-10-29 11:43:44 EDT
As for fixing undocumented stuff: I would like to fix all other warnings first, so that only "undocumented" warnings remain, and then perhaps interested students over here can work on documenting stuff that is missing. I could even organize a documentation marathon event, but that will not happen soon enough for 3.13; 3.14 or 3.15 is much more realistic target.

P.S.
I forgot to take a look at EXCLUDE = stuff; will do.
Comment 9 Vedran Miletić 2011-10-29 15:42:24 EDT
Created attachment 1266 [details]
Doxygen fixes (updated patch)

This fixes all but undocumented stuff and undefined references.
Comment 10 Tommaso Pecorella 2011-10-31 06:54:37 EDT
The patch is... well... huge. It's also a bit hard to separate what's been changed for consistency (@ with \) and what to fix errors.

Normally I'd ask to separate the patch in two, one to just fix errors and the other one to do the consistency changes, but nvm, separating them now would be a real pain, and not really worth. Plus, we're talking about broken documentation, so what could go bad, some more documentation broken? No. Some more errors? No. Go ahead.

+1

PS: yes, I checked the patch, just not all the lines one by one.
Comment 11 Vedran Miletić 2011-10-31 07:09:10 EDT
Thanks for review Tommaso. Missing documentation patches will be separated per module and per person who did them. We plan to start with core this week.
Comment 12 Vedran Miletić 2011-11-02 16:54:50 EDT
OK, we started with core, but this is a _lot_ of work. There is over 900 undocumented functions just in core. (Around 400 in network.)

Me and my students can deal with those two in a month or two (it's not trivial; we need to check what a function does and document that).

If we want to get the whole ns-3 documented anytime soon, we need more people working on this.

Tom, is the patch acceptable for checking in? Is there anything I else need to fix?
Comment 13 Tom Henderson 2011-11-03 00:35:17 EDT
(In reply to comment #12)

> 
> Tom, is the patch acceptable for checking in? Is there anything I else need to
> fix?

I scanned the patch; it has some fixes but seems to be mostly style changes (changing @ to \).  I would hesitate to check this whole patch in as-is without some buy in from the authors and maintainer about making purely style changes.
Comment 14 Vedran Miletić 2011-11-03 06:15:14 EDT
Tommaso, I think a have a way to split it that isn't painful.

Tom, I will split out the real changes from style changes. Does that mean that parts that fix errors are OK?

Also, if we document core and in the process we also fix style consistency and move some docs around files (e. g. from .cc to .h) and groups, that is OK because it's not purely style changes and because it's all in a single module?
Comment 15 Mathieu Lacage 2011-11-04 11:56:09 EDT
NACK to gigantic stylistic changes. This is one too many.

I have tried to review the patch but I do not have enough bandwidth to filter out the non-stylistic changes from the actually useful content.
Comment 16 Vedran Miletić 2011-11-04 12:25:55 EDT
Thanks for the review Mathieu. Will attach a no-style-fixes patch in a minute.
Comment 17 Vedran Miletić 2011-11-04 13:07:36 EDT
Created attachment 1267 [details]
Doxygen patch that fixes erros without style changes
Comment 18 Vedran Miletić 2011-11-04 13:08:13 EDT
Wasn't a minute exactly, but the idea worked.

Hope this is good.
Comment 19 Tommaso Pecorella 2011-11-04 16:41:46 EDT
Created attachment 1268 [details]
Topology-reader docs fixing
Comment 20 Tommaso Pecorella 2011-11-04 16:47:19 EDT
Please find in the latest attachment some improvement to the topology-reader module docs.
1) fixed 2 warnings about missing documentation
2) added a .rst description for the manual (hope it works, I can't compile it right now 'cuz Lion broke dia).
3) changed a bit the documentation so the classes do show up in the module list. (added \ingroup topology to all the classes).

I'd be happy if you could check if the manual renders properly and, in case, push it on the main repository. 

Cheers,

Tommaso
Comment 21 Tommaso Pecorella 2011-11-06 11:47:24 EST
Created attachment 1269 [details]
Topology docs fixings

Found the way to compile the manual, fixed the pdf layout and more.
Comment 22 Tommaso Pecorella 2011-11-16 19:49:12 EST
I think we should push Vedran's patch (at least the one to fix the bugs) before 3.13.

Also, mind if I push the TopologyReader one since I'm the maintainer ? Anyone had the time to check it ?

Cheers,

Tommaso
Comment 23 Tom Henderson 2011-11-17 01:39:02 EST
(In reply to comment #22)
> I think we should push Vedran's patch (at least the one to fix the bugs) before
> 3.13.

Agreed.  I asked Mitch to have a look at committing this, among a couple of other doxygen-related things.

> 
> Also, mind if I push the TopologyReader one since I'm the maintainer ? Anyone
> had the time to check it ?

Please push it, unless you really would like to wait for someone to review (in which case, let me know).
Comment 24 Mathieu Lacage 2011-11-17 05:08:44 EST
(In reply to comment #18)
> Wasn't a minute exactly, but the idea worked.
> 
> Hope this is good.

+1 if you checked that the style checker does not undo some of your changes after you run it on top of your patch
Comment 25 Tommaso Pecorella 2011-11-17 12:45:29 EST
Comment on attachment 1269 [details]
Topology docs fixings

Applied the patches to fix TopologyRead module
Comment 26 Mitch Watrous 2011-11-17 14:35:34 EST
The patch modifies the doxygen configuration file so that doxygen will scan the example directories in each module.

Is that what people want?

Here is the description for the doxygen tag that controls this behavior:

    The EXAMPLE_PATH tag can be used to specify one
    or more files or directories that contain example 
    code fragments that are included (see the
    \include command).

Before the patch:

    EXAMPLE_PATH           = 

After the patch:

    EXAMPLE_PATH           = src/aodv/examples \
                             src/bridge/examples \
                             src/click/examples \
                             src/config-store/examples \
                             src/core/examples \
                             src/csma/examples \
                             src/csma-layout/examples \
                             src/dsdv/examples \
                             src/emu/examples \
                             src/energy/examples \
                             src/flow-monitor/examples \
                             src/internet/examples \
                             src/lte/examples \
                             src/mesh/examples \
                             src/mobility/examples \
                             src/mpi/examples \
                             src/netanim/examples \
                             src/network/examples \
                             src/nix-vector-routing/examples \
                             src/olsr/examples \
                             src/openflow/examples \
                             src/point-to-point/examples \
                             src/propagation/examples \
                             src/spectrum/examples \
                             src/tap-bridge/examples \
                             src/template/examples \
                             src/tools/examples \
                             src/topology-read/examples \
                             src/uan/examples \
                             src/virtual-net-device/examples \
                             src/visualizer/examples \
                             src/wifi/examples \
                             src/wimax/examples
Comment 27 Vedran Miletić 2011-11-17 14:52:21 EST
IMHO yes; files src/core/model/callback.h and src/core/model/simulator.h already include examples, and I believe that as we progress with Doxygen cleanup there will be more examples included.
Comment 28 Mitch Watrous 2011-11-17 17:41:09 EST
I don't think that the stylistic changes I found outweigh the value of the patch.

But, there are many changes in the patch that might be considered stylistic.

For example, the patch adds spaces before \{ and \} tags:

    diff -r 159633363724 src/mesh/model/dot11s/peer-management-protocol.h
    --- a/src/mesh/model/dot11s/peer-management-protocol.h	Mon Oct 31 12:13:18 2011 +0000
    +++ b/src/mesh/model/dot11s/peer-management-protocol.h	Fri Nov 04 18:06:33 2011 +0100
    @@ -82,7 +82,7 @@
        * \param beaconTiming beacon timing element (needed by BCA)
        */
       void ReceiveBeacon (uint32_t interface, Mac48Address peerAddress, Time beaconInterval, Ptr<IeBeaconTiming> beaconTiming);
    -  //\}
    +  // \}
       /**
        * \brief Methods that handle Peer link management frames
        * interaction:
    @@ -125,9 +125,9 @@
        * \brief Checks if there is established link
        */
       bool IsActiveLink (uint32_t interface, Mac48Address peerAddress);
    -  //\}
    +  // \}
       ///\name Interface to other protocols (MLME)
    -  //\{
    +  // \{

The patch also replaces some some / characters with space characters that appear before a \{  or \} tag:

    diff -r 159633363724 src/mesh/model/dot11s/peer-management-protocol-mac.h
    --- a/src/mesh/model/dot11s/peer-management-protocol-mac.h	Mon Oct 31 12:13:18 2011 +0000
    +++ b/src/mesh/model/dot11s/peer-management-protocol-mac.h	Fri Nov 04 18:06:33 2011 +0100
    @@ -45,26 +45,30 @@
       PeerManagementProtocolMac (uint32_t interface, Ptr<PeerManagementProtocol> protocol);
       ~PeerManagementProtocolMac ();
       ///\name Inherited from plugin abstract class
    -  ///\{
    +  // \{
       void SetParent (Ptr<MeshWifiInterfaceMac> parent);
       bool Receive (Ptr<Packet> packet, const WifiMacHeader & header);
       bool UpdateOutcomingFrame (Ptr<Packet> packet, WifiMacHeader & header, Mac48Address from, Mac48Address to);
       void UpdateBeacon (MeshWifiBeacon & beacon) const;
    -  ///\}
    -  ///\name Statistics:
    -  ///\{
    +  // \}
    +  ///\name Statistics
    +  // \{
       void Report (std::ostream &) const;
       void ResetStats ();
       uint32_t GetLinkMetric (Mac48Address peerAddress);
    -  ///\}
    +  // \}
Comment 29 Tom Henderson 2011-11-18 00:30:32 EST
(In reply to comment #28)
> I don't think that the stylistic changes I found outweigh the value of the
> patch.
> 
> But, there are many changes in the patch that might be considered stylistic.
> 
> For example, the patch adds spaces before \{ and \} tags:

I'm not sure whether it is purely stylistic; \\\ is for single-line comments, while these lines have curly braces to start multi-line grouping.  However, I agree that at this point, I would just as soon commit it even if there were a few whitespace changes.
Comment 30 Vedran Miletić 2011-11-18 02:31:32 EST
Thanks for the review Mitch. If I recall correctly, Doxygen even complained about ///\{ and wanted // \{ instead (i.e. 2 slashes instead of 3). What I'm certain, however, is that this is the way of writing it per Doxygen manual.

Thanks Tom. Hope the commit happens soon.
Comment 31 Mitch Watrous 2011-11-18 12:25:30 EST
Should I commit the patch?
Comment 32 Tom Henderson 2011-11-27 00:15:11 EST
(In reply to comment #30)
> Thanks for the review Mitch. If I recall correctly, Doxygen even complained
> about ///\{ and wanted // \{ instead (i.e. 2 slashes instead of 3). What I'm
> certain, however, is that this is the way of writing it per Doxygen manual.
> 
> Thanks Tom. Hope the commit happens soon.

pushed your latest patch in changeset 57ba46094a0d
Comment 33 Vedran Miletić 2011-11-27 05:44:48 EST
Thanks for the commit.
Comment 34 Jared Ivey 2013-11-15 10:37:54 EST
Created attachment 1712 [details]
MPI modules patch for Doxygen warnings

Only noted two public APIs that required attention.
Comment 35 Tom Henderson 2013-11-15 10:46:01 EST
Created attachment 1713 [details]
current list of doxygen warnings to fix
Comment 36 Tom Henderson 2013-11-15 10:48:49 EST
Created attachment 1714 [details]
the actual warnings

part 1 of actual warnings
Comment 37 Tom Henderson 2013-11-15 10:49:48 EST
Created attachment 1715 [details]
actual warnings (part 2)
Comment 38 Jared Ivey 2013-11-15 16:04:36 EST
Created attachment 1716 [details]
Stats module patch for Doxygen warnings

Patches from both the model and helper directories of the stats module. Confirmed all changes within patch file, and confirmed rebuild of ns-3 including patches.
Comment 39 Daniel L. 2013-11-15 19:15:07 EST
Created attachment 1717 [details]
Patch to partially fix doxygen warnings in wifi module

From ns-3 Sprints on 11/15/2013
Comment 40 Budiarto Herman 2013-11-16 12:49:27 EST
Created attachment 1718 [details]
Patch to fix some doxygen warnings in lte module

From the ns-3 documentation sprint November 15, 2013.

Nicola, I add you in CC list, in case you want to review this first.

-budi-
Comment 41 Nicola Baldo 2013-11-18 05:44:29 EST
(In reply to Budiarto Herman from comment #40)
> Created attachment 1718 [details]
> Patch to fix some doxygen warnings in lte module

+1 for me, thanks for the good work!
Comment 42 Tommaso Pecorella 2013-11-19 16:44:58 EST
Created attachment 1719 [details]
Internet model fixes

This patch fixes all the doxygen warnings in internet/model/ (Internet/helper next).

Please review the NSC related fixes, as I'm not fluent with NSC and some descriptions might be wrong. Ty.
Comment 43 Tommaso Pecorella 2013-11-21 05:05:36 EST
Created attachment 1720 [details]
New Internet docs patch

This new patch eliminates some zombie functions (defined but not implemented) and fixes also the helpers warnings.
Comment 44 Tommaso Pecorella 2013-11-21 14:38:31 EST
Created attachment 1721 [details]
flow-monitor model + helper

This patch fixes all the Doxygen warnings in the flow-monitor module (except for examples and tests)
Comment 45 Tom Henderson 2013-11-25 10:39:59 EST
Created attachment 1724 [details]
log of current doxygen warnings
Comment 46 Tom Henderson 2013-11-25 10:40:34 EST
Created attachment 1725 [details]
summary of current warnings report
Comment 47 Tom Henderson 2013-11-25 10:42:04 EST
Created attachment 1726 [details]
summary of current warnings
Comment 48 Daniel L. 2013-11-26 12:01:10 EST
Created attachment 1727 [details]
A second patch to partially fix doxygen warnings in wifi module

More fix for wifi module
Comment 49 Tommaso Pecorella 2013-11-26 16:56:35 EST
Added a wiki page to track who's working on what.
http://www.nsnam.org/wiki/Doxygen-warnings
Comment 50 Tommaso Pecorella 2013-12-14 11:10:25 EST
Created attachment 1737 [details]
stats Doxygen fixes

Posting the patch and not directly applying because I changed a lot the "stats" Doxygen section.
Comment 51 Tom Henderson 2013-12-15 01:59:53 EST
(In reply to Tommaso Pecorella from comment #50)
> Created attachment 1737 [details]
> stats Doxygen fixes
> 
> Posting the patch and not directly applying because I changed a lot the
> "stats" Doxygen section.

I am fine with the changes, except for one statement below, so I suggest applying now.

"Probes are a special kind of Data Aggregator"

should read instead:

"Probes are a special kind of Trace Source"
Comment 52 Tommaso Pecorella 2013-12-15 03:05:23 EST
Comment on attachment 1737 [details]
stats Doxygen fixes

Pushed
Comment 53 Tommaso Pecorella 2014-03-02 17:02:24 EST
Created attachment 1790 [details]
Network module fixes

Network module fixed. Well, not the test and examples, but everything else is fixed.

It might be needed to re-check the \ingroup things, but at least all is documented.

Feel free to check the content...
Comment 54 Tommaso Pecorella 2014-03-02 17:21:19 EST
The network module fixes contains a spurious optimisation to
address.cc's static uint8_t AsInt (std::string v)

The same function is used in other places, but like I said in a mail, that function is basically useless (it can be replaced with a single standard library call, and it's 10x faster too).

I'd remove all the AsInt functions to be honest. However, probably it's best to do it in a separate patch.
Comment 55 Vedran Miletić 2014-03-12 15:37:34 EDT
(In reply to Tommaso Pecorella from comment #53)
> Created attachment 1790 [details]
> Network module fixes
> 
> Network module fixed. Well, not the test and examples, but everything else
> is fixed.
> 
> It might be needed to re-check the \ingroup things, but at least all is
> documented.
> 
> Feel free to check the content...

A lot of very good work here. I particularly like RED queue stuff.

 * ByteTagList::Iterator BeginAll (void) const
 Shouldn't you have \brief Returns an iterator pointing to the very first tag in this list.?
 * ItemIterator, PacketMetadata, Item, ByteTagIterator, PacketTagIterator, Packet constructors, same as above
 * Just a minor thing: I would prefer changes to
  * strtoul()
  * noBUFFER_FREE_LIST
  * friend bool operator < (Ipv4Address const &a, Ipv4Address const &b)
 to be a separate patch.

Otherwise +1.
Comment 56 Tommaso Pecorella 2014-03-13 04:28:58 EDT
Hi,

the minor things you pointed out have been pushed in a previous patch (strtoul), or are typos (noBUFFER_FREE_LIST).

The friend operator is mostly cosmetic, as it's helping the docs to be in the right place.

I've improved the doc a bit about the other things you mentioned. I guess the docs can be refined further at a later stage.

T.
Comment 57 Tommaso Pecorella 2014-03-13 04:36:59 EDT
Comment on attachment 1790 [details]
Network module fixes

Pushed in changeset 10657:6531a8817def
Comment 58 natale.patriciello 2014-10-03 11:04:17 EDT
Created attachment 1890 [details]
Point-to-point documentation patch

Fixes all warning into the module
Comment 59 Tommaso Pecorella 2014-10-03 11:16:07 EDT
Created attachment 1891 [details]
Internet module fixes
Comment 60 Tom Henderson 2014-10-03 16:04:31 EDT
Created attachment 1892 [details]
mobility patch from Tiago
Comment 61 Tommaso Pecorella 2014-10-03 16:58:36 EDT
Created attachment 1893 [details]
propagation models patch

This patch also removes some unused functions, variables and custom PI definitions.
Comment 62 Budiarto Herman 2014-10-05 16:28:47 EDT
Created attachment 1896 [details]
Patch to fix some doxygen warnings in lte module

From the ns-3 documentation sprint October 3, 2014.
Comment 63 Peter Barnes 2014-10-06 13:38:29 EDT
Created attachment 1897 [details]
Asn1 header docs from Tommaso
Comment 64 Tom Henderson 2014-10-06 14:11:38 EDT
(In reply to Peter Barnes from comment #63)
> Created attachment 1897 [details]
> Asn1 header docs from Tommaso


Wow, I should gripe about more files if this is the result :)  (thanks)

I will plan to apply all of the pending patches today.
Comment 65 Tommaso Pecorella 2015-03-01 05:29:38 EST
*** Bug 766 has been marked as a duplicate of this bug. ***
Comment 66 Tommaso Pecorella 2015-03-01 05:36:40 EST
Created attachment 1982 [details]
Sphinx docs for propagation module

The propagation model sphinx docs is still (almost) empty.

This patch "only" adapts the doxygen models descriptions and places then also in the .rst.

In my opinion it's good to have the descriptions in both places: it saves a lot of time.

There are two models still to document/clarify.
One is the JakesPropagationLossModel, and I asked Kirill to provide some more infos, the other one is the Cost231PropagationLossModel.
About the Cost231, I guess that the manual should be amended, as there's a lot of confusion: the Okamura-Hata model it referring to the Cost231 formulas, and the Cost231 model description is absent.
I think that we must clarify the models relationship and how they are different.
Comment 67 Tommaso Pecorella 2015-05-22 11:19:09 EDT
Created attachment 2040 [details]
some small fixes

Some small fixes, dunno why but they're not caught by the normal logs. It's not exhaustive, these are just the ones I found.
Comment 68 Tommaso Pecorella 2015-05-23 18:25:43 EDT
Created attachment 2041 [details]
Internet module fixes

Not applying directly because it contains a function removed.
It is a static function that is only declared. It is not implemented and removing it seems to be safe (no compilation errors).
Why it was there... no idea. Once upon a time it was marked as "internal". I guess it was removed at some point.
Comment 69 Tom Henderson 2015-05-23 19:20:07 EDT
(In reply to Tommaso Pecorella from comment #68)
> Created attachment 2041 [details]
> Internet module fixes
> 
> Not applying directly because it contains a function removed.
> It is a static function that is only declared. It is not implemented and
> removing it seems to be safe (no compilation errors).
> Why it was there... no idea. Once upon a time it was marked as "internal". I
> guess it was removed at some point.

I think it is safe to remove
Comment 70 Tommaso Pecorella 2015-05-25 05:12:24 EDT
Created attachment 2043 [details]
Spectrum model stuff

Not just documentation...
Comment 71 Tommaso Pecorella 2015-08-22 06:53:07 EDT
Created attachment 2120 [details]
updated patch for the Spectrum model
Comment 72 Peter Barnes 2015-11-11 23:11:00 EST
I updated the table here:
https://www.nsnam.org/wiki/Doxygen-warnings#Doxygen_work_status

This excludes tests and examples.  The total is 9237 warnings, so great progress.  Are we sure we're ready for last call?  Or do we still want to push progress on doxygen?
Comment 73 Tom Henderson 2015-11-12 00:56:24 EST
The last call state was in reference to the two lingering patches that were from earlier this year, from Tommaso, which I just pushed.

I would like to keep fixing these, so I moved the state back to Patch Wanted.
Comment 74 Tommaso Pecorella 2016-01-23 13:02:52 EST
Created attachment 2249 [details]
OLSR documentation update.
Comment 75 Tommaso Pecorella 2016-01-23 13:04:18 EST
Created attachment 2250 [details]
OLSR uncrustified

To be applied on top of patch 2249. Perhaps it's a bit too zealous, but if one is at it...
Comment 76 Tommaso Pecorella 2016-03-11 15:41:01 EST
Comment on attachment 2249 [details]
OLSR documentation update.

changeset 12025:e56715abf931
Comment 77 Robert Ammon 2016-12-18 21:06:40 EST
File updates to correct doxygen errors uploaded as http://codereview.appspot.com/313230043
Comment 78 Robert Ammon 2016-12-19 21:35:36 EST
In reference to https://www.nsnam.org/wiki/Doxygen-warnings#Doxygen_work_status, and the use of doxygen.warnings.report.sh, I have submitted an enhancement (Bug 2592) to doxygen.warnings.report.sh to add an -S option to sort the log file alphabetically by file name (-s was already taken).
Comment 79 Robert Ammon 2017-01-03 01:18:05 EST
I have uploaded modified files to resolve all DOXYGEN warnings (with a few exceptions, primarily python files) for all SRC folders (except LTE which still has thousands of warnings for just that model) for the non Test and Example subfolders.

The uploaded changes also resolve all DOXYGEN warnings for all Test and Example subfolders for the SRC folders Antenna through Mesh, excluding LTE.

The latest patch set is a comprehensive set of files.  The remaining warnings will be resolved over the next week and uploaded as a new patch set, however, due to the large number of files modified, I would like to see integration of the already modified files into the baseline started so all of the modifications can be in place for the NS 3.27 release.

Please ignore the file doc/doxygen.warnings.report.sh which was uploaded in error.
Comment 80 Peter Barnes 2017-01-05 16:11:59 EST
+1 for committing Robert's work at http://codereview.appspot.com/313230043

I'll add some notes for follow up in a subsequent comment here.
Comment 81 Tommaso Pecorella 2017-01-05 19:03:02 EST
(In reply to Peter Barnes from comment #80)
> +1 for committing Robert's work at http://codereview.appspot.com/313230043
> 
> I'll add some notes for follow up in a subsequent comment here.

I'm honestly impressed by Robert's work, but I'd not commit it as it is.
Some fixes are simply perfect, some others are... not so perfect.

Examples:
src/wave/model/channel-scheduler.h
- the 3 initializers are not explained, and in 2 o them the params are not documented.
- the ChannelAccess enumeration elements are not documented.
src/wimax/model/wimax-tlv.h
- Serialize, Deserialize and GetSerializedSize shouldn't be documented (they are virtual, the documentation is inherited from the base class)
- CommonTypes enumeration elements are not documented
- "/// constructor" is redundant (personal opinion), but when it is documented, the params must be documented as well.
- some functions params / return types are not documented

Without diminishing the astonishing quantity and quality of Robert's work, I'd give a 4th review to the patch set.
As for myself, I'll pick all the changes in the modules I maintain and I'll push them (if nobody minds).
Comment 82 Peter Barnes 2017-01-05 20:31:02 EST
- the ChannelAccess enumeration elements are not documented.
src/wimax/model/wimax-tlv.h
- CommonTypes enumeration elements are not documented
- "/// constructor" is redundant (personal opinion), but when it is documented, the params must be documented as well.
- some functions params / return types are not documented

IMO undocumented elements should not block commit like this; they will still show up as undocumented, and we can come back and fill them in.

- the 3 initializers are not explained
- "/// constructor" is redundant
- Serialize, Deserialize and GetSerializedSize shouldn't be documented (they are virtual, the documentation is inherited from the base class)

Uninformative docs are a problem, and should be omitted, since they mislead us into thinking it's done, and makes it much harder to find and fix later.
Comment 83 Robert Ammon 2017-01-14 23:46:08 EST
I have uploaded updates to resolve the review comments.  Except for LTE and 2 other files, doxygen warnings for all modules have been resolved. 

I have created a tarball of the updated files but the size is 8 MB so it wont attach here.

If you send me an E mail, I will sent the tarball.
Comment 84 Tommaso Pecorella 2017-01-16 20:47:43 EST
I'm sorry if I'm pedantic, but I'm (slowly) committing patches to the modules I maintain and I'm using Robert's work as a guideline.

The main differences are:
1) Triple check the parameters documentation
2) \ingroup and \defgroup use
3) Clearer explanation of the function / member variables.

Point 1 could be skipped, just because missing stuff will generate errors.

Point 2 is for clarity, and I think it is important.
Each module should have a *clear* distinction between classes used in the module, in the examples and in the tests.
Moreover, test and example classes should be (also) grouped in a separate meta-group.
Little known fact: a class can belong to two or more groups, just use more /ingroup.

Point 3 is the most critical / controversial. As much as I hate Doxygen errors, I hate even more to have a function poorly documented (and not generating errors).
In this case the user will be unhappy-confused-angry and the badly documented functions will be even harder to spot.
Comment 85 Robert Ammon 2017-01-22 23:56:38 EST
Changes to correct doxygen warnings for the LTE module have been uploaded as  http://codereview.appspot.com/315450043
Comment 86 Robert Ammon 2017-01-28 19:40:57 EST
Additional (final?) changes needed to address all review comments for the Antenna module have been uploaded as http://codereview.appspot.com/319190043
Comment 87 Tommaso Pecorella 2017-01-28 19:42:28 EST
I'm going to push a fix for all the changes in the Internet module.

(In reply to Robert Ammon from comment #86)
> Additional (final?) changes needed to address all review comments for the
> Antenna module have been uploaded as http://codereview.appspot.com/319190043
Comment 88 Tommaso Pecorella 2017-01-28 21:57:55 EST
Please note that I'm using this system:
1) At the beginning of one of the tests of each module I a defgroup, e.g.:
/**
 * \ingroup internet
 * \defgroup internet-test internet module tests
 */

2) In each class belonging to the test of each module, I added the proper ingroup(s), e.g.:
 * \ingroup internet-test
 * \ingroup tests

The "tests" group is defined in the tests module.

In this way the classes used in the tests are:
1) Visualized in a single sub-group in the doxygen page, and they don't mess with the module "normal" classes, and
2) Are collected in a single place too.
Comment 89 Robert Ammon 2017-01-28 23:04:15 EST
Additional (final?) changes needed to address all review comments for the AODV module have been uploaded as http://codereview.appspot.com/320060043
Comment 90 Robert Ammon 2017-01-28 23:16:53 EST
Additional (final?) changes needed to address all review comments for the applications module have been uploaded as http://codereview.appspot.com/318350043
Comment 91 Robert Ammon 2017-01-29 00:21:48 EST
Additional (final?) changes needed to address all review comments for the brite module have been uploaded as http://codereview.appspot.com/314360043
Comment 92 Robert Ammon 2017-01-29 01:24:39 EST
Additional (final?) changes needed to address all review comments for the buildings module have been uploaded as http://codereview.appspot.com/317140043
Comment 93 Robert Ammon 2017-01-29 13:11:32 EST
Additional (final?) changes needed to address all review comments for the config-store module have been uploaded as http://codereview.appspot.com/316200043
Comment 94 Robert Ammon 2017-01-29 22:09:41 EST
Additional (final?) changes needed to address all review comments for the core module have been uploaded as http://codereview.appspot.com/318360043
Comment 95 Robert Ammon 2017-01-29 23:34:51 EST
Additional (final?) changes needed to address all review comments for the dsdv module have been uploaded as http://codereview.appspot.com/320070043
Comment 96 Robert Ammon 2017-01-30 19:22:30 EST
Additional (final?) changes needed to address all review comments for the dsr module have been uploaded as http://codereview.appspot.com/319200043
Comment 97 Robert Ammon 2017-01-30 19:36:12 EST
Additional (final?) changes needed to address all review comments for the energy module have been uploaded as http://codereview.appspot.com/318390043
Comment 98 Robert Ammon 2017-01-31 13:22:34 EST
Additional (final?) changes needed to address all review comments for the mesh module have been uploaded as http://codereview.appspot.com/317150043
Comment 99 Robert Ammon 2017-01-31 13:56:51 EST
Additional (final?) changes needed to address all review comments for the mobility module have been uploaded as http://codereview.appspot.com/311600043
Comment 100 Robert Ammon 2017-01-31 14:31:35 EST
Additional (final?) changes needed to address all review comments for the mpi module have been uploaded as http://codereview.appspot.com/318390044
Comment 101 Robert Ammon 2017-01-31 18:07:56 EST
Additional (final?) changes needed to address all review comments for the netanim module have been uploaded as http://codereview.appspot.com/319230043
Comment 102 Robert Ammon 2017-01-31 19:00:44 EST
Additional (final?) changes needed to address all review comments for the network module have been uploaded as http://codereview.appspot.com/318410043
Comment 103 Robert Ammon 2017-01-31 19:34:14 EST
Additional (final?) changes needed to address all review comments for the nix-vector-routing module have been uploaded as http://codereview.appspot.com/319230044
Comment 104 Robert Ammon 2017-01-31 20:43:24 EST
Additional (final?) changes needed to address all review comments for the openflow module have been uploaded as http://codereview.appspot.com/313490043
Comment 105 Robert Ammon 2017-01-31 21:02:31 EST
Additional (final?) changes needed to address all review comments for the propagation module have been uploaded as  http://codereview.appspot.com/313500043
Comment 106 Robert Ammon 2017-01-31 21:39:14 EST
Additional (final?) changes needed to address all review comments for the spectrum module have been uploaded as  http://codereview.appspot.com/320100043
Comment 107 Robert Ammon 2017-01-31 22:52:04 EST
Additional (final?) changes needed to address all review comments for the stats module have been uploaded as http://codereview.appspot.com/317170043
Comment 108 Robert Ammon 2017-02-01 00:28:32 EST
Additional (final?) changes needed to address all review comments for the test module have been uploaded as http://codereview.appspot.com/316240043
Comment 109 Robert Ammon 2017-02-01 01:12:18 EST
Additional (final?) changes needed to address all review comments for the traffic-control module have been uploaded as http://codereview.appspot.com/315510043
Comment 110 Robert Ammon 2017-02-01 19:31:44 EST
Additional (final?) changes needed to address all review comments for the uan module have been uploaded as http://codereview.appspot.com/319260043
Comment 111 Robert Ammon 2017-02-01 19:48:46 EST
Additional (final?) changes needed to address all review comments for the virtual-net-device module have been uploaded as http://codereview.appspot.com/320110043
Comment 112 Robert Ammon 2017-02-01 22:18:13 EST
Additional (final?) changes needed to address all review comments for the visualizer module have been uploaded as http://codereview.appspot.com/319270043
Comment 113 Robert Ammon 2017-02-02 00:10:05 EST
Additional (final?) changes needed to address all review comments for the wave module have been uploaded as http://codereview.appspot.com/311610044
Comment 114 Robert Ammon 2017-02-02 00:28:29 EST
Additional (final?) changes needed to address all review comments for the utils module have been uploaded as http://codereview.appspot.com/320120043
Comment 115 Robert Ammon 2017-02-02 22:15:21 EST
Additional (final?) changes needed to address all review comments for the examples module have been uploaded as http://codereview.appspot.com/318430043
Comment 116 Robert Ammon 2017-02-04 19:49:50 EST
Additional (final?) changes needed to address all review comments for the wimax module have been uploaded as http://codereview.appspot.com/318460043
Comment 117 Robert Ammon 2017-02-05 15:01:56 EST
Additional (final?) changes needed to address all review comments for the wifi module have been uploaded as http://codereview.appspot.com/313560043.

There is one file model/vht-wifi-mac-helper.h that I have not been able to figure out the solution to the doxygen warning.  If someone else could take a look at that file and see what the resolution is.
Comment 118 Robert Ammon 2017-02-05 23:56:04 EST
Additional (final?) changes needed to address all review comments for the lte module have been uploaded as http://codereview.appspot.com/311650043
Comment 119 Robert Ammon 2017-02-06 17:06:30 EST
Additional changes needed to correct warning for the latest changes to the internet module have been uploaded as http://codereview.appspot.com/313570043
Comment 120 Robert Ammon 2017-02-06 22:59:46 EST
I have completed all updates required to correct the doxygen warnings.  There are two files that have one warning each left, I have not been able to determine the correction(s) required.  The affected files are:

Count File
----- ----------------------------------
      1 src/visualizer/visualizer/ipython_view.py
      1 src/wifi/helper/vht-wifi-mac-helper.h
----------------------------------------
     2 files with warnings

I would like to see all of the changes incorporated ASAP.  The changes to LTE and WIFI over the last week or two have introduced 100-200 new doxygen warnings that I have corrected.

IMHO, the only way to permanently solve the issue of doxygen warnings is to get these corrections merged and then modify the master build options to fail a build if there are doxygen warnings so they are corrected immediately.  Not only will this ensure that doxygen warnings to not creep back into the project, it will also improve the doxygen comments since they will be made by the original developer which should be much higher in quality than those made later by maintainers.
Comment 121 Tom Henderson 2017-02-07 09:45:41 EST
(In reply to Robert Ammon from comment #120)
> I have completed all updates required to correct the doxygen warnings. 
> There are two files that have one warning each left, I have not been able to
> determine the correction(s) required.  The affected files are:
> 
> Count File
> ----- ----------------------------------
>       1 src/visualizer/visualizer/ipython_view.py
>       1 src/wifi/helper/vht-wifi-mac-helper.h
> ----------------------------------------
>      2 files with warnings
> 
> I would like to see all of the changes incorporated ASAP.  The changes to
> LTE and WIFI over the last week or two have introduced 100-200 new doxygen
> warnings that I have corrected.
> 
> IMHO, the only way to permanently solve the issue of doxygen warnings is to
> get these corrections merged and then modify the master build options to
> fail a build if there are doxygen warnings so they are corrected
> immediately.  Not only will this ensure that doxygen warnings to not creep
> back into the project, it will also improve the doxygen comments since they
> will be made by the original developer which should be much higher in
> quality than those made later by maintainers.

Robert, thank you for this great effort.  I agree that we should treat future warnings as a build error and clean them immediately.
Comment 122 Robert Ammon 2017-02-16 00:09:52 EST
Additional changes needed to correct warning for the latest changes to the olsr module have been uploaded as http://codereview.appspot.com/318550043
Comment 123 Tom Henderson 2017-02-17 14:18:05 EST
Status (Feb 17 2017): modules still requiring patches to be committed:

antenna
aodv
brite
buildings
config-store
core
dsdv
dsr
energy
lte
mesh
mpi
netanim
network
nix-vector
openflow
spectrum
utils
virtual-net-device
visualizer
wave
wifi
wimax
Comment 124 Robert Ammon 2017-02-17 15:24:29 EST
A couple of updates to Tom's comment.

1) Wifi should be complete.  There still some doxygen errors in the output but those should be corrected once the changes for Core are merged.

2) One additional item that needs to be included is Examples (directly under the ns-3-dev folder).

3) I have been downloading other changes as they are being made and updating them as needed to correct additional doxygen errors introduced.  In this case, I have updated the patch set posted to Reitveld as needed.  Modules where the most recent changes need to be merged are Test and Examples.
Comment 125 Robert Ammon 2017-02-20 00:08:21 EST
List of modules that still need merged should also include applications.
Comment 126 Robert Ammon 2017-02-23 00:11:36 EST
The Propagation module should be added to the list of outstanding modules.
Comment 127 Robert Ammon 2017-02-25 20:20:16 EST
(In reply to Robert Ammon from comment #114)
> Additional (final?) changes needed to address all review comments for the
> utils module have been uploaded as http://codereview.appspot.com/320120043

Additional changes uploaded with corrections for latest external changes.
Comment 128 Robert Ammon 2017-04-02 16:23:09 EDT
Latest doxygen warning status

Report of Doxygen warnings
----------------------------------------

(All counts are lower bounds.)

Warnings by module/directory:

Count Directory
----- ----------------------------------
   1530 src/wimax/model
    513 src/core/test
    507 src/mesh/model
    261 src/netanim/model
    248 src/visualizer/visualizer
    227 src/dsr/model
    192 src/wave/model
    156 src/core/model
    127 src/aodv/model
    123 src/visualizer/model
    109 src/test/ns3tcp
    108 src/config-store/model
    106 src/network/test
     89 src/wave/examples
     85 src/mpi/model
     74 src/dsdv/model
     65 src/wifi/model
     65 src/mobility/test
     63 src/propagation/test
     63 src/mesh/test
     61 src/test/traced
     61 src/energy/model
     61 src/buildings/model
     55 src/wave/test
     49 src/antenna/test
     46 src/openflow/model
     45 src/test/csma-system-test-suite.cc
     44 src/spectrum/test
     44 src/buildings/test
     39 src/wave/helper
     39 examples/wireless/multirate.cc
     37 src/buildings/helper
     31 src/aodv/test
     30 examples/wireless/power-adaptation-interference.cc
     28 src/brite/helper
     26 src/dsdv/examples
     26 examples/stats/wifi-example-apps.h
     25 src/stats/test
     23 src/netanim/examples
     23 examples/wireless/power-adaptation-distance.cc
     22 src/wimax/test
     22 src/nix-vector-routing/model
     22 examples/wireless/mixed-network.cc
     21 src/stats/examples
     19 src/spectrum/model
     18 src/virtual-net-device/examples
     18 src/antenna/model
     17 src/virtual-net-device/model
     17 src/test/ns3wifi
     17 src/netanim/test
     17 src/energy/examples
     16 src/energy/helper
     15 src/mesh/helper
     15 src/mesh/examples
     15 examples/routing/manet-routing-compare.cc
     14 src/dsr/test
     12 examples/tutorial/fifth.cc
     10 src/nix-vector-routing/examples
     10 src/network/examples
      9 src/wimax/helper
      9 src/test/ns3tc
      9 src/energy/test
      8 src/olsr/test
      8 src/dsr/helper
      8 src/core/examples
      8 src/aodv/examples
      8 examples/wireless/wifi-clear-channel-cmu.cc
      8 examples/wireless/rate-adaptation-distance.cc
      7 examples/wireless/wifi-adhoc.cc
      6 src/propagation/examples
      4 src/network/utils
      4 examples/tutorial/sixth.cc
      4 examples/tutorial/seventh.cc
      3 src/wifi/helper
      3 src/openflow/test
      3 src/lte/test
      3 src/dsdv/test
      3 src/config-store/examples
      3 src/brite/test
      2 src/traffic-control/model
      2 src/flow-monitor/model
      2 examples/tutorial/fourth.cc
      1 src/stats/model
      1 src/applications/test
      1 examples/wireless/wifi-spectrum-per-interference.cc
 47 additional undocumented parameters.
----------------------------------------
  5995 total warnings
    85 directories with warnings
Comment 129 Robert Ammon 2017-07-10 22:49:24 EDT
Doxygen corrections for latest DHCP modification to module internet-apps has been uploaded to http://codereview.appspot.com/329800043
Comment 130 Tom Henderson 2017-08-19 19:34:55 EDT
In trying to finish up the Doxygen work, I'm having some difficulty with suppressing warnings due to macro expansions.  This is with the latest Doxygen release (1.8.13).

As of changeset 13048:c00059ef50e4, Doxygen warnings report is reporting 64 warnings in the wifi module.  These are all due to macro expansions; e.g.:

Filtered Warnings
========================================
src/wifi/model/dsss-parameter-set.cc:100: warning: return type of member ns3::MakeDsssParameterSetChecker is not documented
src/wifi/model/dsss-parameter-set.h:111: warning: Compound ns3::DsssParameterSetValue is not documented.
src/wifi/model/dsss-parameter-set.h:111: warning: Member DsssParameterSetValue(const DsssParameterSet &value) (function) of class ns3::DsssParameterSetValue is not documented.

from

/// DsssParameterSet
ATTRIBUTE_HELPER_CPP (DsssParameterSet);

I looked at doxygen.conf and found that these were all listed for expansion under the EXPAND_AS_DEFINED setting.  I'm not sure why we need anything documented more than the original macro definition in src/core/model/attribute-helper.h.  So I disabled these in doxygen.conf:

-EXPAND_AS_DEFINED      = ATTRIBUTE_ACCESSOR_DEFINE \
-                         ATTRIBUTE_CHECKER_DEFINE \
-                         ATTRIBUTE_CHECKER_IMPLEMENT \
-                         ATTRIBUTE_CHECKER_IMPLEMENT_WITH_NAME \
-                         ATTRIBUTE_CONVERTER_DEFINE \
-                         ATTRIBUTE_HELPER_CPP \
-                         ATTRIBUTE_HELPER_HEADER \
-                         ATTRIBUTE_VALUE_DEFINE \
-                         ATTRIBUTE_VALUE_DEFINE_WITH_NAME \
-                         ATTRIBUTE_VALUE_IMPLEMENT \
-                         ATTRIBUTE_VALUE_IMPLEMENT_WITH_NAME
+EXPAND_AS_DEFINED      =

but I still get a number of warnings as a result:

Filtered Warnings
========================================
src/wifi/model/dsss-parameter-set.h:111: warning: Member ATTRIBUTE_HELPER_HEADER(DsssParameterSet) (function) of namespace ns3 is not documented.
src/wifi/model/edca-parameter-set.h:408: warning: Member ATTRIBUTE_HELPER_HEADER(EdcaParameterSet) (function) of namespace ns3 is not documented.
src/wifi/model/erp-information.cc:124: warning: Member ATTRIBUTE_HELPER_CPP(ErpInformation) (function) of namespace ns3 is not documented.

I didn't expect those since the SKIP_FUNCTION_MACROS tag is set to YES.  Any ideas?

If Doxygen can't handle these macros, should we filter these out in doxygen.warnings.report.sh?
Comment 131 Peter Barnes 2017-08-21 15:52:11 EDT
The current doxygen.conf is correct.  Attribute documentation is created by 
utils/print-introspected-doxygen.cc:866

This ensures that the symbols created by macro expansion *do* get documented.  
Prior to this change searching for FooValue would return nothing, which is 
frustrating for new users.

This is documented in ATTRIBUTE_HELPER_HEADER:
https://www.nsnam.org/doxygen/group__attributehelper.html#details

I grepped for all uses of ATTRIBUTE_VALUE_HEADER and found these new ones 
missing from the list in print-introspected-doxygen.cc:

DsssParameterSet
EdcaParameterSet
ErpInformation
HeCapabilities
HtOperation
VhtCapabilities
VhtOperation
Comment 132 Tom Henderson 2017-08-21 16:06:33 EDT
(In reply to Peter Barnes from comment #131)
> The current doxygen.conf is correct.  Attribute documentation is created by 
> utils/print-introspected-doxygen.cc:866

Thanks for clarifying; I did not think to look there.  I will patch print-introspected-doxygen.cc

- Tom