The openWNS API at docs.openwns.org is incomplete

[Jan]

The API documentation at docs.openwns.org is only partially available. Whole namespaces are missing. For example, the ofdmaPhy namespace is missing completely, see:

http://docs.openwns.org/api/namespaces.htm

I had a similar problem with a previous version of the simulator / SDK. One part of the solution was to use a specific doxygen version (1.5.3). Maybe this helps.

[Karsten Klagges (karsten.klagges)]

The documentation only shows documentation for documented namespaces. Undocumented namespaces are not shown in the namespace list. Although, the undocumented namespaces exist and are listed in the alphabetical class list, for example. Usually it doesn't make sense to list undocumented namespaces explicitly.

If you wish to make the documentation for the ofdmaphy namespace appear, we would appreciate your documentation input.

To keep the api documentation usable, we will not make doxygen to extract all available classes, namespaces and files. This would tend to a huge site of predominant trivial content.

[Jan (jan-ellenbeck)]

OK, I see that the alphabetical list of all classes shows much more. However, if I build the documentation from a vanilla openwns-sdk with doxygen 1.5.3, I see all the available namespaces on that page and I prefer it this way.

The situation is the same for the list of all classes, only documented classes are shown. Imagine a user is looking for information about the beamforming antenna. He will only find wns::service::phy::ofdma::BeamForming because this is listed due to its short annotation. What he will not find - and maybe that's what he was really looking for - is rise::antenna::Beamforming. Note that the page exists on docs.openwns.org (http://docs.openwns.org/api/classrise_1_1antenna_1_1Beamforming.htm) but simply isn't linked.

In my opinion it is confusing to hide classes that actually exist just because they do not have this short text description. But that's just my 2cents.

[Daniel Bültmann (daniel.bueltmann)]

I also share Jan's view. We should include all classes regardless of
whether they are documented or not.
I also like it to have browsable source code of each class to view it
online. Often the best documentation
is the source code itself ;). And in our case the source code ist mostly
the only documentation that is available ;)

Jan schrieb:
> OK, I see that the alphabetical list of all classes shows much more.
> However, if I build the documentation from a vanilla openwns-sdk with
> doxygen 1.5.3, I see all the available namespaces on that page and I
> prefer it this way.
>
> The situation is the same for the list of all classes, only documented
> classes are shown. Imagine a user is looking for information about the
> beamforming antenna. He will only find
> wns::service::phy::ofdma::BeamForming because this is listed due to its
> short annotation. What he will not find - and maybe that's what he was
> really looking for - is rise::antenna::Beamforming. Note that the page
> exists on docs.openwns.org
> (http://docs.openwns.org/api/classrise_1_1antenna_1_1Beamforming.htm)
> but simply isn't linked.
>
> In my opinion it is confusing to hide classes that actually exist just
> because they do not have this short text description. But that's just my
> 2cents.
>
>

[Maciej Muehleisen (mue-comnets)]

I totally agree

Daniel Bültmann wrote:
> I also share Jan's view. We should include all classes regardless of
> whether they are documented or not.
> I also like it to have browsable source code of each class to view it
> online. Often the best documentation
> is the source code itself ;). And in our case the source code ist mostly
> the only documentation that is available ;)
>
>
> Jan schrieb:
>
>> OK, I see that the alphabetical list of all classes shows much more.
>> However, if I build the documentation from a vanilla openwns-sdk with
>> doxygen 1.5.3, I see all the available namespaces on that page and I
>> prefer it this way.
>>
>> The situation is the same for the list of all classes, only documented
>> classes are shown. Imagine a user is looking for information about the
>> beamforming antenna. He will only find
>> wns::service::phy::ofdma::BeamForming because this is listed due to its
>> short annotation. What he will not find - and maybe that's what he was
>> really looking for - is rise::antenna::Beamforming. Note that the page
>> exists on docs.openwns.org
>> (http://docs.openwns.org/api/classrise_1_1antenna_1_1Beamforming.htm)
>> but simply isn't linked.
>>
>> In my opinion it is confusing to hide classes that actually exist just
>> because they do not have this short text description. But that's just my
>> 2cents.
>>
>>
>>
>
>

[Karsten Klagges (karsten.klagges)]

I still have a different opinion:

The goal of the API documentation is to provide information about how to work with the API. Which means, there should be detailed information about what the intention of specific classes and their methods are. There can be information about method parameters and return values, typedefs and how components of the framework interact.

The API documentation should not explain how the implementation works or how a specific method is implemented. Actually this is not necessary to use the API.

If we decide to extract all classes from the source code, doxygen creates a webpage that contains the name of the class, the names of the member functions and all member variables. Even if the names are well chosen, the API user still would have to browse the source code which can easily be done in the IDE of your choice. In the end the purpose of the doxygen-documentation of undocumented class is at least questionable.

By the way. Launchpad provides a source code browser not only for the mainline of the openWNS but also for all branches. Do we need an additional source code browser in the API documentation?

[Marc Schinnenburg (marc.schinnenburg)]

Could it be useful (and is it possible) to generate and offer both? Then it is up to the liking of the reader.

[Daniel Bültmann (daniel.bueltmann)]

We had a discussion on this topic offline this morning. We came to the agreement that we should extract all classes and namespaces regardless of whether they are documented or not. We also decided to include the source code in the API documentation. The reasons for this decision are:

 1. Although it would be nice to hide implementation details and internals in the documentation, we don't have the information available what is an import public class and what is an internal.
 2. Because we have a quite low documentation coverage simply dropping all undocumented classes is not an option.
 3. The source code is also included. We assume that not all users have a IDE running. Understanding an implementation means that you need to understand the semantic dependencies between parts of the implementation. Doxygen offers you to explore these dependencies.
  3b. You can browse the openWNS source code "offline" without having a local copy of the source code.

I reverted the changes and also did some cleanup on the documentation build process. I will commit the patch today.