oship-dev team mailing list archive

[Diego Manhães Pinheiro <dmpinheiro@xxxxxxxxx>]

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