oship-dev team mailing list archive

[Tim Cook <timothywayne.cook@xxxxxxxxx>]

Hi Diego,

I fully appreciate your points.  The documentation/testing issue still
exists for the RM.

Regards,
Tim


On Mon, 2010-06-28 at 20:22 -0300, Diego Manhães Pinheiro wrote:
> 
> 
> 2010/6/28 Tim Cook <timothywayne.cook@xxxxxxxxx>
>         Hi Diego,
>         
>         Thanks for the prompt reply.
>         
>         On Mon, 2010-06-28 at 15:19 -0300, Diego Manhães Pinheiro
>         wrote:
>         >
>         > In fact, I implement this behaviour. I think a can explain
>         why I
>         > choose this way: that way I find to solve the circular
>         problem[1].
>         > It's more simple that it sounds. Take a look at the
>         history.txt[1]
>         > file where have tests that exercise the behaviour properly.
>         Just a
>         > hint: You don't have to interact directly with that
>         EventContainer
>         > object.Your focus is History object, right ? Try to pass a
>         list of
>         > events at the object instantiation. Anyway, look at the
>         history.txt
>         > doctest to help you.
>         
>         
>         I do not have time right now to take an in-depth look at it.
>          But I
>         understand your approach. It seems to be a usable solution to
>         the
>         circular import problem by abstracting away those offending
>         attributes.
>         
>         >
>         > The EventContainer really isn't defined in the openEHR
>         specification.
>         > In the specification it was defined as a list[2].
>         
>         
>         Correct; a list that can only contain instances of Events.
>         
>         > If you think more generically the intention to use a List
>         object is
>         > define a collection of objects. I prefered use the Container
>         object
>         > than a List object why it solved fast and pretty well, IMHO.
>         I also
>         > could change that to use a diferent class such as a
>         PersistentList
>         > object [3]. This is a implementation concern that have to be
>         > discussed.
>         
>         
>         There are pros for this choice especially in path to object
>         creation.
>         
>         
>         >
>         >         There is not any documentation on them either.
>          There should
>         >         be a
>         >         blueprint or a bug report stating the necessity for
>         them as
>         >         well as some
>         >         documentation on their purpose and usage if they are
>         in fact
>         >         required.
>         > Ok. Tests are not exactly documentation. If we look at this
>         > affirmation, I could say all OSHIP code don't have a good
>         > documentation.
>         
>         
>         You COULD say that; but it wouldn't be true.  Every Interface
>         and Class
>         have a docstring and the package (file) documentation
>         references you to
>         exactly the module out of more than 1000 pages of
>         specification
>         documentation. That equals pretty well documented, I think.
> That's the point!
> Just to clarify: It wasn't my intention to offend the documentation.
> The tests, interfaces and python docstrings have a essential role on
> the documentation and the OSHIP Project had a acceptable cover on
> this. I'm certainly sure about it. But I reconsider the fact when
> someone needs a high view, an text documentation helps a lot,
> especially when you have to explain specific things or things that
> have too much knowledge in the background.
> The point that cannot be forgotten is the implementation details. Use
> doctest on both of the situations(tests in general and specific
> documentation) helps if you have in mind use the Sphinx, the project
> documentation generator[1], that automate dramatically the process to
> generate a project documentation. In my point of view, this a topic to
> consider if you think about to mix the two types of documentation. The
> own python language use it to define it's documentation[2] and it's
> awesome!
> Now, let me resume my considerations : I believe that exist
> implementation details that cannot be explained perfectly only by code
> and tests.
> 
> 
> [1] - http://sphinx.pocoo.org/
> [2] - http://docs.python.org/
> 
> 
>         
>         > Anyway, the doctest that did looks like a documentation.
>         Take a look
>         > and find out it's ok.
>         
>         
>         It seems to be complete enough for implementation by others.
>         
>         However, we are working on a large project with many people in
>         various
>         geographic locations.  We also have an obligation to funding
>         agencies to
>         account for our progress so that funding may continue. It is
>         imperative
>         that the tools available on Launchpad are used for their
>         intended
>         purposes.  Use of these tools and the mailing list is crucial
>         for a
>         coherent working environment and good project management.
> I totally agree with you. 
>         
>         Thank You,
>         Tim
>         
>         
>         
>         
> 
> 
> 
> -- 
> http://dmpinheiro.net
> -----------------------------------
> Diego Manhães Pinheiro
> _______________________________________________
> Mailing list: https://launchpad.net/~oship-dev
> Post to     : oship-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~oship-dev
> More help   : https://help.launchpad.net/ListHelp

-- 
***************************************************************
Timothy Cook, MSc

LinkedIn Profile:http://www.linkedin.com/in/timothywaynecook 
Skype ID == (upon request)
Academic.Edu Profile: http://uff.academia.edu/TimothyCook

You may get my Public GPG key from  popular keyservers or    
from this link http://timothywayne.cook.googlepages.com/home

Attachment: signature.asc
Description: This is a digitally signed message part