docs update

[Richard Bateman]

After looking at the history and noticing that it's been a few weeks
since the documentation was last updated, I went ahead and regenerated
and updated the html docs. I'm getting better at documenting, but I'll
need to go back and fix a few inconsistencies.

I think there was someone else who was going to work a lot on the
help... since you haven't committed anything, I just decided to throw
this in for now. hope I'm not stepping on toes =]

the main thing updated is that DbObject is mostly documented and there
is a lot more documented in DbConnection.

More to come next time I have time to work on it.

Richard

[Rick Gigger]

On Apr 22, 2008, at 12:54 AM, Richard Bateman wrote:

> After looking at the history and noticing that it's been a few weeks
> since the documentation was last updated, I went ahead and regenerated
> and updated the html docs. I'm getting better at documenting, but
> I'll
> need to go back and fix a few inconsistencies.
>
> I think there was someone else who was going to work a lot on the
> help... since you haven't committed anything, I just decided to throw
> this in for now. hope I'm not stepping on toes =]

It certainly doesn't hurt to update it. I've been debating how much
good it does to keep it updated in svn but I guess when people check
it out it's good to have the info as up to date as possible. Mark is
going to be in charge of handling releases and he will always update
the docs before rolling a new tarball, but we might as well rebuild
the api docs any time we add significant documentation. I think we
should always make sure that we do the following two things though: 1.
always make sure that we use the command at http://code.google.com/p/zoop/source/browse/trunk/update_api_docs.sh
. We can update the command, just make sure the new command always
gets commited. 2. when you commit new api docs don't commit anything
else with it so you don't have to sort through a million files to find
the relevant changes.

> More to come next time I have time to work on it.

Awesome. Thanks!

Rick

[Richard Bateman]

Rick Gigger wrote:
> It certainly doesn't hurt to update it. I've been debating how much
> good it does to keep it updated in svn but I guess when people check
> it out it's good to have the info as up to date as possible. Mark is
> going to be in charge of handling releases and he will always update
> the docs before rolling a new tarball, but we might as well rebuild
> the api docs any time we add significant documentation. I think we
> should always make sure that we do the following two things though: 1.
> always make sure that we use the command at http://code.google.com/p/zoop/source/browse/trunk/update_api_docs.sh
> . We can update the command, just make sure the new command always
> gets commited. 2. when you commit new api docs don't commit anything
> else with it so you don't have to sort through a million files to find
> the relevant changes.

That's more or less how I felt about it. I realized after I committed
that that I should have committed even the changes to the comments that
I made separately from the api docs themselves. I did use your
update_api_docs.sh file to generate it, though.

As I get better at the syntax for the docs, I hope the documentation
will get a little more usable.

Do we have a server anywhere that is "non-critical" enough to put a
"live" copy of the docs on? And maybe a working copy of the examples,
just for people to look at? Just brainstorming on how to help people
get started easier. I know this is the "extreme development version",
but eventually we'll want to start making branch releases to the stable
branch of zoop. I don't think we're quite there yet, but we're getting
there quickly as we make changes and improvements, so I'm just thinking
ahead. Also, if you don't mind, I may invite a few other people to use
this version of the framework.

Richard

[Mark Suman]

That's more or less how I felt about it.  I realized after I committed
that that I should have committed even the changes to the comments that
I made separately from the api docs themselves.  I did use your
update_api_docs.sh file to generate it, though.

As I get better at the syntax for the docs, I hope the documentation
will get a little more usable.

Thanks for updating the API doc.  I will be taking care of that now that school is out.  Next week I start at Apple and will have a fairly regular schedule, so I can push out new API and tarballs on a regular basis.

 

Do we have a server anywhere that is "non-critical" enough to put a
"live" copy of the docs on?  And maybe a working copy of the examples,
just for people to look at?  Just brainstorming on how to help people
get started easier.  I know this is the "extreme development version",
but eventually we'll want to start making branch releases to the stable
branch of zoop.  I don't think we're quite there yet, but we're getting
there quickly as we make changes and improvements, so I'm just thinking
ahead.  Also, if you don't mind, I may invite a few other people to use
this version of the framework.

Richard

I can host it on my server, which is strictly used for development; however, it will be offline this summer during July and August.  So, I can host it for now if you like.  It's on Comcast, but should be enough for now.

Mark

[Rick Gigger]

Richard, I've had this flagged to respond to for months, but am now
finally getting around to it.

Not that I know of. Could we put it on main zoop server that hosts
the main zoop website? It wouldn't be linked into the main webstie of
course but we could link it in to the google code site or provide
links to it in the downloadable source.

> And maybe a working copy of the examples,
> just for people to look at?

Yeah, I have wanted this for a while. I should ask around and see if
someone has some spare server resources they want to loan us. Traffic
is so small right now that I doubt anyone would really even notice it
there.

> Just brainstorming on how to help people
> get started easier.

Yes, that has been one of my goals, to get people up and running as
quickly as possible.

> I know this is the "extreme development version",
> but eventually we'll want to start making branch releases to the
> stable
> branch of zoop.

Right now there are some people using it for production systems and I
work with them individually to resolve their issues, fix bugs, and
help them deal with any changes in the API. If I do anything that has
any major backwards compatibility breaks I will probably make special
branches for them.

As far as having an official stable branch though, I'm not sure what
is going to happen. Originally we were going to eventually declare
mine the stable branch and include elements of old zoop in it for
backwards compatibility. Since then though development has picked up
on the current stable branch and Steve has started making plans to
take stable components from new zoop and merge them into old zoop. So
zoop 2.0 will be old zoop with the good, stable stuff from new zoop
merged into it.

It is still possible though that I will at some point want to have
official "stable" releases of just my stuff. At that point we will
need to figure out how to deal with the brand confusion of having
multiple stable zoop libs. I might need to release it under a
different name if that were to happen, unless it could completely
replace old zoop.

> I don't think we're quite there yet, but we're getting
> there quickly as we make changes and improvements, so I'm just
> thinking
> ahead.

Yeah, I'm not sure how it's all going to play out, I'm just playing it
by ear at this point.

> Also, if you don't mind, I may invite a few other people to use
> this version of the framework.

Yes, the more the better. It would be good to get some feedback from
them though. Traffic on the mailing list is pretty light. Have you
talked to any of them about their experience?

Thanks,

Rick

[Rick Gigger]

On Apr 22, 2008, at 8:57 AM, Richard Bateman wrote:

> Also, if you don't mind, I may invite a few other people to use
> this version of the framework.

Oh, yeah, one more thing about this. It might be good to help people
to know which parts of the system are stable and which are not. I
don't see the main MVC changing significantly but there is a lot of
stuff in zoop that is totally experimental. I had created this page http://code.google.com/p/zoop/wiki/ModuleStatus
to keep track of it but I don't know how up to date it is.

Thanks,

Rick