MySQLDocumentationInCompletionReview
Review page for MySQL documentation in completion
This page is used to manage the review of MySQLDocumentationInCompletion.
The value of this approach is that it allows me to track all the issues separately and to drive them to resolution. For me email reviews although nice and informal are almost impossible to track to conclusion. Inline comments to the main document muddy up the document and are also difficult to track to conclusion.
The review process works like this:
- Add a comment header of the format "Comment <initials>-<number> (<status>)" (see below for examples)
- A discussion then can take place under that comment header
- Each comment will have a status at the top, with the status set to Approved, Accepted PDU (pending doc update) or Unresolved
- If necessary, we do more rounds of discussion until the item is marked as Approved
Contents |
Commenter Initials Key
- DVC - David Van Couvering
- JB - John Baker
Feedback
DVC01 - HelpSet versus Function API
This document describes two separate features - providing MySQL documentation as a help set and providing function documentation in completion. It would be good if these were separated out
JB01 - agree
DVC02 - HelpSet as plugin?
You don't describe that the full HelpSet will be made available as a plugin and won't be part of the main release. I think that's important to mention.
JB02 - OK
DVC03 - Keywords
I'm not sure I understand the need for keywords to uniquely identify a function. Isn't the name and the number of parameters sufficient. I could have sworn that was the information we got back from the MySQL folks. Are there cases where there are two functions with the same number of arguments that are different because of the number of keywords?
Also, I think what you are calling "keywords" are actually just parameter names, aren't they?
JB03 There are 2 functions with the same number of arguments plus keywords, substring and substr The MySQL documentation uses the term "keyword" also referred to as reserved words. Here's the list of reserved words An example is SUBSTRING(str FROM pos FOR len) where FROM and FOR are keywords.
DVC04 - Use cases for completion
These are great, thanks.
DVC05 - Pluggable API
I was talking about this feature with Jayashri yesterday, and it quickly became clear that we want a pluggable API. This makes it easier for our users/partners to provide function documentation for other database vendors besides MySQL.
As a user of the API, what I will have is some identifier for the vendor - I think this is something we should add to the DB explorer API - and then I can look up the appropriate implementation of an interface based on the vendor identifier.
As per the standard NetBeans approach, we should have an API and an SPI. Providers implement the SPI and users use the API.
This isn't *essential* for this release, but at a minimum we should keep this design in mind so that we can refactor it to an API/SPI approach in the future.
JB05 - good idea
