[jira] Commented: (DERBY-4065) Provide documentation for XPLAIN style statistics processing

["Kim Haase (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/DERBY-4065?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12707077#action_12707077 ] 

Kim Haase commented on DERBY-4065:
----------------------------------

Sorry for the delay, Bryan!

These are really good -- I am not the technical expert, but the topics are very well written and clear. There are only a few fixes that seem significant -- some should be done before you commit, some can wait.

src/tuning/tuningderby.ditamap: 
I think you may not have done an svn update before editing this file, because it reverts to the 10.4 version and 2008 date. (The Reference Manual map file doesn't have this problem.) The patch command fails on the non-updated part.

src/tuning/ctun_xplain_tables.dita:
In the concept element, the id value should be 

<concept xml:lang="en-us" id="ctun_xplain_tables">

instead of

<concept xml:lang="en-us" id="ctun_xplain_tables.dita">

(This is the convention observed in all the files to make xrefs work. I notice that the new topics in the Reference Manual use the correct convention for their id values.)

src/tuning/ctun_xplain_style.dita:
Same id issue as with ctun_xplain_tables.dita.

Also, in this topic you might want to point people to the Reference Manual for info about the tables and system functions/procedures.

Similarly, in the Reference Manual you might want to add some cross-references. From the procedure/function topics and the main tables topic, you could point to the Tuning Guide information on how to use xplain mode. Also, the topics on the functions and procedures could point to the main topic on the tables. The references in the table topics could be improved: some of them contain a general mention of the "RUNTIMESTATISTICS section" of the reference manual; if this section is really in the reference manual you could refer to the exact topic, but I suspect the "Working with RunTimeStatistics" section of the tuning guide might be what's intended.

An actual error, I think: in rref_syscs_set_xplain_schema.dita, there's a reference to SYSCS_UTIL.SYSCS_SET_XPLAIN_STYLE, whose name has changed.

The syntax statement for SYSCS_UTIL.SYSCS_GET_XPLAIN_MODE doesn't say what the function returns, as the syntax for SYSCS_UTIL.SYSCS_GET_XPLAIN_SCHEMA does. Should it? (Is it an INTEGER or a SMALLINT?)

Some of the table topics have "FIXME" and some queries in the descriptions, so I hope you get those questions answered. These topics also have "Derby" hard-coded instead of <ph conref="../conrefs.dita#prod/productshortname"></ph>, but I imagine you are waiting for the text to solidify before you make that fix.


> Provide documentation for XPLAIN style statistics processing
> ------------------------------------------------------------
>
>                 Key: DERBY-4065
>                 URL: https://issues.apache.org/jira/browse/DERBY-4065
>             Project: Derby
>          Issue Type: Sub-task
>          Components: Documentation
>            Reporter: Bryan Pendleton
>            Assignee: Bryan Pendleton
>            Priority: Minor
>         Attachments: ctun_xplain_mode.html, ctun_xplain_mode.html, ctun_xplain_tables.html, earlyDraftDocs.diff, earlyDraftDocs.diff, earlyDraftDocs.diff, earlyDraftDocs.diff, rrefresetxplaintablesproc.html, rrefsetxplainmodeproc.html, rrefsetxplainstyleproc.html, rrefsyscsgetxplainmode.html, rrefsyscsgetxplainstyle.html, rrefsysxplain_resultset_timings.html, rrefsysxplain_resultsets.html, rrefsysxplain_resultsets.html, rrefsysxplain_scan_props.html, rrefsysxplain_scan_props.html, rrefsysxplain_sort_props.html, rrefsysxplain_statement_timings.html, rrefsysxplain_statements.html, rrefsysxplain_statements.html, userSchema.diff
>
>
> This sub-task of DERBY-2487 is for tracking the documentation of the new feature. I think
> it will be a little bit simpler to track the documentation changes in a separate issue.

-- 
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.