Missing documentation and incorrect / incomplete examples

[GoogleCodeExporter]

The only documentation available for SimD is the incomplete Dr. Dobb's
Journals references (
http://www.drdobbs.com/architecture-and-design/222900238 ).  The examples
from the article do not work as is.  The code snippets listed in the
article do not even reflect the code contained in the demo directory that
the article directs the user to visit.

As an example:

//FROM DDJ
/**********************************************************
* DataReader
**********************************************************/
dds::Topic< TempSensorType> tsTopic("TempSensorTopic");
dds::sub::DataReader< TempSensorType> dr(tsTopic);
dds::sub::SampleInfoSeq info;
TempSensorSeq data;
while (true) {
   dr.read(data, info);
   for (int i =0; i < data.length(); ++i)
   std::cout < <  data[i] < <  std::endl;
   sleep(1);
}
============
/************************************************
* SIMD DEMO (lightly edited for better comparison)
*************************************************/
  dds::Topic<TempSensorType> tsTopic("TempSensor");
  /* SNIP add params */
  dds::ContentFilteredTopic<TempSensorType> cfTsTopic("TempSensor-1",
                                                      tsTopic,
                                                      argv[1],
                                                      params);
  dds::DataReader<TempSensorType> dr(cfTsTopic);
  DDS::SampleInfoSeq status;
  TempSensorTypeSeq data;
  while (true) {
    dr.read(data, status);
    for (unsigned int i = 0; i < data.length(); ++i) {
      std::cout << data[i] << std::endl;
    }
    dr.return_loan(data, status);
    sleep(1); 
  }
  return 0;

----

The DDJ example code shows a dds::sub:: scoping which is not present in the
actual code example. 

Also, the DDJ example does not return_loan() after the read cycle.

Additionally, you have two (confusing!) namespaces:  DDS and dds.  In the
actual code, you distinguish between the two namespaces, whereas in the
example there is no distinction.  

The QueryCondition does not seem to work as described in the DDJ article.
Even though there is a listing, there is no code example in the DDJ samples
for QueryCondition.

These are issues with just a few examples; other examples/ presentations
are equally incomplete or incorrect.

How do you expect SimD to be adopted if there is no documentation, and the
scant documentation that exists is self-contradictory?

Original issue reported on code.google.com by 22samu...@gmail.com on 19 Apr 2010 at 4:01

[GoogleCodeExporter]

Hello 22samurai, sorry for causing pains with the slight incoherence between 
what shown in the DDJ article 
and what included in the SimD distribution. To give you some context, the "DDS" 
namespace you see comes 
from the existing C++ API used by OpenSplice DDS. Most of those types should be 
typedef-ed into the "dds" 
namespace but that was not done in SimD v0.7 (as you'll see this is not the 
case in v0.8). 

Concerning the lack of documentation, I tend to agree with you that there is 
not much, yet, things are 
improving version from version. 

Finally, as explained in the Wiki, SimD is an incubator project for the new ISO 
C++ API for DDS, and for all 0.x 
version the API will be subject to changes. From v1.x it will be implementing 
the full ISO C++ API for DDS 
which in currently under standardization at the OMG.

Original comment by angelo.corsaro@gmail.com on 15 May 2010 at 11:09

[GoogleCodeExporter]

Original comment by angelo.corsaro@gmail.com on 15 May 2010 at 11:11

• Changed state: Accepted
• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

Something else you might want to look at is the SimD presentation I gave at the 
OMG Real-Time Workshop this 
past May 25th, see http://bit.ly/cEE5km 

Original comment by angelo.corsaro@gmail.com on 26 May 2010 at 6:40