List of connection properties?

[EgonHugeist]

@Fr0st,

Btw, very good way to check correctness of Zeos hierarchy is to rename both dbc and component source folders, comment out ZTestDbc/ZTestComponents in test project and try to build it. Then uncomment dbc and build.

Hope it's done already..

I can't get why TZClientVariantManager was moved, it doesn't seem to use any of the dbc stuff (maybe I'm wrong though).

That's because of the consettings which are Dbc-speciffic and not relevant on core layer.

@aehimself
ill have a look to your editor proposal. I've added and enabled my idea of such an property editor for the TZConnection/TZTransaction today morning..
Feel free to test and share your findings. Proposals changes are welcome. It's just the first "make it work" approach..

[EgonHugeist]

@aehimself

i had a look to your work. You did invest a loads of time!
To be honest i downloaded it twice, i remember to see it already.

Why i didn't apply the code:
You ListBox seems to have two columns. D7 dosn't support it. Also was it to Windows spezialized. That than means it's not portable for FPC. Thus not portable and can't be committed that way.
OTH great job!

The committed editor hase some more tweaks, like filtering per protocol, diff list view etc.
The property editor is enabled for the TZConnection.Properties, TZTransaction.Properties, TZReadOnlyDataSet.Properties, TZQuery.Properties, TZTable.Properties.

Critics, remarks, tests, issue reports are welcome.

Little remarks:
In current state i use records, containing a purpose description, supported Protocols and Provides. If we would have an parser, which could read the help insight comments we could parse Fr0st's ZDbcProperties.pas, add a match code using the constant name. That way we could use a pas2doc to create doc's from Fr0st's collection. Volunteers? OTH we could use the Properties-Array i made to generate documantation..

[marsupilami]

If we would have an parser, which could read the help insight comments we could parse Fr0st's ZDbcProperties.pas

Erm - every modern Delphi (last 10 years?) does that. More or less it is in the menu under Project -> Options -> Building -> Delphi Compiler -> Compiling -> Other Options -> Generate XML documentation.
We only would need to parse the xml file afterwards. Also I am pretty sure, it doesn't output the value of the string constants in use - so we wouldn't really get the options real names. This is one reason for me to prefer the record solution. The record solution also can be used by third party programs easily - like third party SQL tools that want to show the options that Zeos supports.

[EgonHugeist]

Jan i didn't know that option.
Made a quick test:

Code: Select all

  
  /// <see cref: String> </see>
  /// <summary>
  ///  Format to read date & time, like YYYY-MM-DD HH:NN:SS.F
  /// </summary>
  /// <remarks>
  ///  Just simple formats are supported. ISO 8601 is prefered.
  ///  If the driver(f.e. SQLite) supports the 'T' delimiter do not hasitate to use!
  /// </remarks>
  ConnProps_DateTimeWriteFormat = 'DatetimeWriteFormat';
  /// <type>Enum</type>
  /// <values>
  ///  Off|On
  /// </values>
  /// <default>
  ///  On
  /// </default>
  /// <summary>
  ///  A short summary
  /// </summary>
  /// <remarks>
  ///  if not set we tread it as "on"
  /// </remarks>
  ConnProps_test = 'test';

the returned XML Node:

Code: Select all

  <const name="ConnProps_DateTimeWriteFormat" type="string" file="..\..\src\dbc\ZDbcProperties.pas" line="129">
    <devnotes>
       <see cref: String> </see>
       <summary>
        Format to read date &amp; time, like YYYY-MM-DD HH:NN:SS.F
       </summary>
       <remarks>
        Just simple formats are supported. ISO 8601 is prefered.
        If the driver(f.e. SQLite) supports the 'T' delimiter do not hasitate to use!
       </remarks>
    </devnotes>
    <value>
      DatetimeWriteFormat
    </value>
  </const>
  <const name="ConnProps_test" type="string" file="..\..\src\dbc\ZDbcProperties.pas" line="152">
    <devnotes>
       <type>Enum</type>
       <values>
        Off|On
       </values>
       <default>
        On
       </default>
       <summary>
        A short summary
       </summary>
       <remarks>
        if not set we tread it as "on"
       </remarks>
    </devnotes>
    <value>
      test
    </value>
  </const>

Means type can be added by the <see> field, a summary, remarks, and the value is contained too. The more we can add nodes like "default", "Values" etc. Might not be helpful for help insight, however. What do you think?

[marsupilami]

Hmm - I think it is a bit like abusing Help Insight ;o) Since I am not doing the work, I am not the one to make a decision here. So - what are the pros and cons:

Using Help Insight compatible comments:
Pro:

• Easy to use - we already know how to write that kind of comments.
• Documentation is where the constant is defined. They are located next to each other.

Cons:

• I doubt that the usual developer will use the constants. They will have a look at the documentation and then do something like "Connection.Properties.Add('sslcert=' + CertFileName')". So they will never see our work.
• The information is not available right away to the Delphi property editor and to end user programs like the SQL tool of aehimself. Making it available would be a two step process like -> compile Zeos and get the XML file generated by Delphi -> generate a pas file from that -> recompile Zeos.

Using a cusom solution:
Pro:

• We get the information right away in the property editor and in user programs.
  Cons:
• Probably more clumsy. Developers have to find the information on how to document new constants.
• I didn't look at the source code (sorry Michael, I didn't take the time). But I assume we still are using a somewhat static file for this. This might get inapropriate to use because parameters will grow and not get less.

In my opinion we should keep to our own documentation system for parameters. It easily allows us to access documentation for parameters during runtime. I think this outweighs the burden on the developer to remember how to do that. It might make sense to have a kinda documentation registration function for parameters:

Code: Select all

RegisterParameter(['mssql', 'sybase'], plConnection, 'workstation', stString, 'The workstation name to send to the server.')

This would allow to keep the documentation of parameters in the units where we define their meaning. Also when drivers are disabled in the Zeos.inc their parameters would not be registered automatically.

[Fr0sT]

All in all, what we have:
- Descriptions in sources

what we want:
- Descriptions in IDE code editor (when sources are accessible).
- Descriptions in IDE visual editors (which are called from BPL => compiled package => no source available but only runtime variables)

I know no option that could help with both use cases with a single source of info. Runtime records won't help when writing the code and descriptions in comments won't be compiled to binary.
So it seems we've to build an additional info storage, be it a source code or some textual file. To keep it consistent without big hassle it should be built automatically => some script or build tool is needed. HelpInsight format is pretty straightforward and could be parsed even without full-featured XML engine. It's native for Delphi and is accepted by Lazarus in more or less usable state.

[*]I doubt that the usual developer will use the constants. They will have a look at the documentation and then do something like "Connection.Properties.Add('sslcert=' + CertFileName')". So they will never see our work.

Well, if docs won't tell the values of parameters but only the names of constants, devs will use them. Any experienced developer comes to "Don't use magic values in code" conclusion so I guess this change encourages good coding style

[marsupilami]

All in all, what we have:
- Descriptions in sources

what we want:
- Descriptions in IDE code editor (when sources are accessible).
- Descriptions in IDE visual editors (which are called from BPL => compiled package => no source available but only runtime variables)

I know no option that could help with both use cases with a single source of info. Runtime records won't help when writing the code and descriptions in comments won't be compiled to binary.
So it seems we've to build an additional info storage, be it a source code or some textual file. To keep it consistent without big hassle it should be built automatically => some script or build tool is needed. HelpInsight format is pretty straightforward and could be parsed even without full-featured XML engine. It's native for Delphi and is accepted by Lazarus in more or less usable state.

[*]I doubt that the usual developer will use the constants. They will have a look at the documentation and then do something like "Connection.Properties.Add('sslcert=' + CertFileName')". So they will never see our work.

Well, if docs won't tell the values of parameters but only the names of constants, devs will use them. Any experienced developer comes to "Don't use magic values in code" conclusion so I guess this change encourages good coding style

Well - our parameters are no "magic values". They are documented (to some degree): https://sourceforge.net/p/zeoslib/wiki/driver parameters/. Even though we could change that wiki page and the Zeos documentation, we also have a gazillion of posts in the forums that mention the names of the parameters. And we cannot change these posts. Also all seasone developers who use Zeos probably know the parameter names they use and will want to continue using them. So trying to make the parameter names something internal that doesn't need to be known to the outside, simply won't work.
And last but not least - if one wants to save these parameters to an configuration file most people will use the parameter names and not the constants. Trying to use the constants names in that use case will make code more ugly and complicated because one has to rely on RTTI. And last but not least: If I do a documentation about parameters that derives from this work, I most probably will document parameter names. It simply is more human readable, more easy to understand.

Sorry - but my vote is for the record solution because it fits in with the past and it requires less work. But then - I am not doing the work so I don't have a say in this. The decision is to be made by the people who do the work. Chances are hight for me to derive PDF parameter documentation from this work then.