Thanks very much for the comments Frank and Kelvin. I hope that this message gets added to the same thread as the other messages , if not then this is in reference to http://www.mail-archive.com/tuscany-dev@ws.apache.org/msg04438.html.
I like the comment about being explicit about the context for each sample and will do so whereever I have not in the javaDoc. I have mixed feelings about how to handle the DataGraph. I think that the sample should demonstrate the creation, and use of both the DataGaph and DataObject representation of the company. This is because this particular example in spec goes over the use of both and it would seem strange not to cover both in the sample. Secondly, the area is so grey in the specification that demonstating to the user how they can obtain an actual DataGraph using the SDOUtil method or avoid it's use are both important. I like the thought about simply encouraging the user to edit the code but think that we would have to provide good example code in the commetns for them to do so and perhaps we may as well just include working code. I think that I will move the code that obtains a DataObject representing a DataGraph into a spec snipet example with comments. If people feel strongly that there should not be user input to determine which is used ( DataObject vrs DataGraph ) for this specific example then my preference would be to use the DataObject as this more closely follows the spec example and also adhere's to the specification. If this path is followed I would also create an additional sample which goes over various means of obtaining a DataGraph from xml in the spec snipet section. I will wait on some replies and then post an update. Thanks very much for all the feedback - anyone else ? Robbie.