Re: [Gramps-devel] Start of some programmer's documentation

[Don A. <don...@co...>]

Thanks for the feedback. I have a few questions that will help me
understand your comments better.

> Why doesn't the Person/Family/Source/... section have any indication it
> lists the respective methods and classes?  The first time I looked at
> the documentation I thought I had stumbled across an introductory
> explanation of the GUI.  After a second reading, and having examined
> the links, the implied oop in reference to "objects" is now plainly
> evident -- this may merely be my background, but this initial
> misunderstanding could be mitigated with the clarification of the
> nature of the objects and the "contents" of the links.
> 
> Why doesn't the API appear to have a section detailing the described
> objects?  (Or perhaps they're buried within the hierarchy?)

The API documentation is generated from the code using epydoc. I haven't
figured out how to do everything yet. All the class functions are
documented, but there is little overall documentation.

Can you provide suggestions on what is missing and how you would like to
see it?

> Are the "undo" actions actually extrapolated from the transaction, or
> does a "reverse" (or undo) transaction need to be written?  (I'd think
> not given the text of the section, but this wasn't particularly clear.)

The "undo" operation is a single command.

  database.undo()

> Given that handles are nothing more than mere python strings, do they
> therefore NOT require closing or freeing (et all)?  I presume this is
> implementation dependent, but does anything require freeing or closing?

Python nicely cleans up everything for you. About the only thing you
have to worry about is closing files. The database cursor function has a
close function because it actually accesses the underlying file.

> One thing that I did notice however is the lack of a quick-start guide
> of sorts.  I'm fairly familiar with a host of other languages, less so
> with python, but could probably pick it up fairly readily if I could
> see a select few commented codes.  I grant I haven't checked the site
> nor the sources lately, but with an indication of how particular
> features were implemented that could likely expedite the creation of
> others -- particularly reports -- the age calculator for example. 
> Pending the report documentation and a bit of free time I'll see if I
> can't accomplish a few of the feature requests.

I hope to add a report tutorial soon, showing the development of a basic
report. It should give a nice overview of the language, the API, and the
report structure.

> Again, what's written looks pretty good -- keep up the good work!

Thanks.

-- 
Don Allingham <don...@co...>