Forum OpenACS Development: Package Documentation: How can we tell if a package is fully documented?

- User Documentation explaining what the package does and how it works.

- Developer documentation that talks about how the package is implemented and its design.

- API is well documented through the use of ad_proc.

- SQL is documented with comments throughout the files.

-Roberto

I was wondering about one more thing: After years of using the older ACS toolkits (4.2, 3.x, 2.x, etc.), I only started using OpenACS with its multi database support and XQL query dispatcher fairly recently. One thing I've noticed, is that with the SQL in the separate xql files, as I scan through the Tcl source code the database commands are often so short that I just miss them entirely.

E.g., take this old style (Oracle only, SQL in the Tcl file) query:

set static_page_id [db_exec_plsql do_sp_new {
  begin
  :1 := static_page.new(
    filename   => :sp_filename
    ,title     => :page_title
    ,folder_id => :parent_folder_id
    ,mime_type => :mime_type
  );
  end;
}]

set static_page_id [db_exec_plsql do_sp_new {}]

I hate the idea of leaving obsolete, non-functional SQL in the Tcl file - doing so has already bitten me more than once. But, is there some other convention that would make the Tcl source code more transparent?

For example, maybe including a marker like this to catch the eye when scanning through code:

set static_page_id [db_exec_plsql do_sp_new {
  --
  -- SQL
  --
}]

set static_page_id [db_exec_plsql do_sp_new {
  -- begin
  -- :1 := static_page.new(
  --   filename   => :sp_filename
  --   ,title     => :page_title
  --   ,folder_id => :parent_folder_id
  --   ,mime_type => :mime_type
  -- );
  -- end;
}]

Or perhaps there's no advantage to any new changes or conventions like this at all, and the current system is fine. For you folks who have been dealing with XQL files for a long time now, what do you think?

I've personally gotten used to looking for the db_ commands, and I appreciate the fact that the code takes up fewer lines so it's easier to see the big picture.

I agree, though, that the situation is not ideal. Swapping between foo.tcl, foo.xql, and foo-yourdb.xql to find the corresponding DB statement is annoying. I like the idea of a script to put the DB statements into the tcl file, but I don't think it's realistic, because that would make all your files locally modified and confuse CVS. Besides, then you start relying on it, and when you forget to keep your xql files and your tcl files in sync, you're going to waste time finding the problem.

I think we should modify the api-browser, though, so it does some regexp'ing on db_ statements to bring the query inline. Maybe that would encourage more people to use the API-browser, and in turn encourage more people to improve the API-browser to include things like links to "real" documentation, overview documentation ("why is the API for this package designed like that"), etc.

/Lars

If anyone wants to tackle this I think it would be great to add for 4.7.  I don't think it would be that large a task.  It's never bubbled high enough up on my own personal task list for me to get started, though.  And of course the longer I live without such a tool the less I feel like I need it :)

Whichever we decide lets make it a standard.  Atleast about 6 months ago the decision was "SQL".  See my Things 2 Remember:

http://www.infiniteinfo.com/openacs/things2remember.html

Okay so it is Friday, later than I thought. I just uploaded a patch to the API Browser that shows source for .tcl, .adp and .xql files. The .xql files are linked to the .tcl file page, so only related .xql files are shown. This patch only covers the content pages, not the library files.