[Gambas-user] CDate Documentation

[BB]

On 12/11/22 7:47 pm, Benoit Minisini wrote:
> Le 11/11/2022 à 18:29, Claus Dietrich a écrit :
>> Hi Benoít
>>
>>  From my humble point of view the documentation of CDate on 
>> http://gambaswiki.org/wiki/lang/cdate has a few issues:
>>
>> 1. CDate converts the date to UTC, when the argument contains a date 
>> and time component. This fact is not mentioned.
>
> No. CDate() does not "convert a date to UTC". It converts a string 
> representation of a date that is assumed to be in UTC into a date value.
>
>>
>> 2. The UTC-Offset is always the current UTC-Offset - even if the 
>> offset at given date/point of time is supposed to be different.
>> Example for the time zone Berlin/Germany:
>> Print CDate("11/11/2022 13:00:00")     -> 11.11.2022 14:00:00
>> Print CDate("08/11/2022 13:00:00")     -> 11.08.2022 14:00:00 (should 
>> actually be 15:00:00)
>> I don't regard this as a bug, but it is important to know. An 
>> according information would be helpful.
>
> Indeed. I don't know if there is some code somewhere in the OS that 
> can take into account every time zone change at any time in any 
> country. I don't think so!
>
>>
>> 3. The provided example may mislead the reader, because it doesn't 
>> show any UTC-offset.
>
> Yes. It's because the playground uses 'en_GB.UTF-8' localization.
>>
>> 4. There is only an indirect mentioning about the mandatory format of 
>> the date component, which must be the US-format mm/dd/yyyy. I suggest 
>> to provide an according information.
>>
>
> Yes.
>
>> 5. The example should have provided a day > 12 to indicate where the 
>> day has to be placed.
>
> Maybe. If 4) is fixed, it should be enough.
>
>>
>> 6. The "run" example is irritating, because in my case it shows a 
>> different result - dd/mm/yyyy instead of dd/mm/yyyy. The reason may 
>> be found in the following point.
>>
>> 7. The result of Print CDate(..) depends on the locale of the 
>> platform. Hence the result of Print CDate on the GambasWiki depends 
>> on the time zone and locale of the server platform. That means, that 
>> visitors may get a different result on their local platform - because 
>> of a different time zone and locale.
>
> Yes. This must be explained clearly too, which timezone is used by the 
> playground server.
>
>>
>>
>> I suggest an according revision of that wiki page.
>>
>
> If you can do that, you are welcome!
>
> Best regards,
>
I would have thought that the complete explanation in the Date & Time 
Management <https://gambaswiki.org/wiki/doc/date> page would have been 
enough for anyone. Perhaps all that is needed is a warning box at the 
top of the page linking to that doc.

I am a *firm* believer that the main documentation should be as brief 
and succinct as possible. Gambas help is generally excellent in that 
respect. I would hate to see something like the godawful Lazarus help 
pop up whenever I am typing some code (or if you-all are really 
masochistic, try the QT documentation for real fun.)  I reckon that:

  * any help that is going to pop up while typing code should be as
    brief as possible
  * any sample code should be as basic as possible
  * any long involved explanations as to why, where, who (and who was
    she with, what they ate etc etc etc) belongs in the *Documents*
    section.

The Documents <https://gambaswiki.org/wiki/doc> and Topics 
<https://gambaswiki.org/wiki/topic> section of the wiki is not used 
enough by many people IMHO.

!

b

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.gambas-basic.org/pipermail/user/attachments/20221112/2e5973f0/attachment-0001.htm>