documentation (was: default values)

[Robert Brenstein]

>On 5/6/05 3:50 PM, "Robert Brenstein" <rjb at robelko.com> wrote:
>
>>  I can't say what the situation is for creating new fields. The doc
>>  mentions CreateField() method when discussing CreateTable on page 35
>>  but I can't find it anywhere else in that doc.
>
>Page 48 - 49
>

Ah, a good example of how API abstraction obfuscates things, so let 
me switch the threads.

No wonder the Acrobat search function did not find anything. One has 
to either know that VTable.CreateField() is CreateStringField(), 
CreateVarCharField(), etc, to search for them specifcally or has to 
browse the doc to find "working with database structure" section and 
figure out that the methods discussed there mean VTable.CreateField() 
elsewhere.

This is probably all super obvious to you, Ruslan, and other db pros 
but let me play a new db developer further.

Now following my search for default values, I gather that they are 
hidden in the inFlags of each CreateXxxxField(), but searching the 
doc for 'inFlags' or 'EVFlag' again produces no hits outside that 
section. What is this EVFlag thing?

Luckily, searching PDF for 'default' produces a hit in section 
discussing field properties, where DefaultValue is defined as 
"asvariant". Aha! So, are flags and properties synonyms in your API? 
What is this "asvariant"? I guess it should be "as variant" (typos 
add to confusion). Neither is defined in this doc.

Another example along those lines: the description of field property 
"Type as EVFieldType" (what the heck is the latter BTW?) says to see 
also "VTable.ChangeType" (bottom of p 57). So I search for it, and... 
no hits. Then what am I to "see also"?

So, is this API abstraction defining items in terms of undefined 
terms really so helpful to each Valentina developer? Wouldn't it be 
simpler to just explain all this in plain English? It would require 
only a few paragraphs instead of numerous pages.

As I said elsewhere, I think this abstracted API should be an 
internal Paradigma doc.

Or am I having a bad day?

Robert