tracker issue : CF-4201871

Issue: some DateTimeFormat() masks are undocumented

Repro:

<cfscript>
  myDateTime = createDateTime(2016,1,3,12,34,56);
  commonMasks = ["d", "dd", "m", "mm", "mmm", "mmmm", "w", "W", "yy", "yyyy", "YYYY", "short", "medium", "long", "full"];//Documented in DateFormat() and DateTimeFormat() docs
  dateFormatMasks = ["ddd", "dddd", "e", "E", "f", "F", "k", "K", "gg", "z", "Z", "X"];//Only documented in DateFormat() doc
  dateTimeFormatMasks = ["EEE", "EEEE", "Y", "YY", "G", "ww", "WW"];//Only documented in DateTimeFormat() doc
  simpleDateFormatMasks = ["M", "L", "D", "u", "a"];//Only documented in SimpleDateFormat doc
  result = queryNew("pattern,isInDateFormatDoc,isInDateTimeFormatDoc,dateFormatOutput,dateTimeFormatOutput", "varchar,bit,bit,varchar,varchar");
  commonMasks.each(function(element) {
    result.addRow([element, true, true, myDateTime.dateFormat(element), myDateTime.dateTimeFormat(element)]);
  });
  dateFormatMasks.each(function(element) {
    result.addRow([element, true, false, myDateTime.dateFormat(element), myDateTime.dateTimeFormat(element)]);
  });
  dateTimeFormatMasks.each(function(element) {
    result.addRow([element, false, true, myDateTime.dateFormat(element), myDateTime.dateTimeFormat(element)]);
  });
  simpleDateFormatMasks.each(function(element) {
    result.addRow([element, false, false, myDateTime.dateFormat(element), myDateTime.dateTimeFormat(element)]);
  });
  writeOutput(myDateTime);
  writeDump(result);
</cfscript>

Actual result: masks "ddd, dddd, eee, eeee, f/F, k, K, z, Z, X, M and D" are undocumented in the DateTimeFormat() doc

Expected result: masks "ddd, dddd, eee, eeee, f/F, k, K, z, Z, X, M and D" are documented in the DateTimeFormat() doc

Notes:
1) "e/E" is documented on DateFormat() but "EEE and EEEE" are documented in DateTimeFormat(). Since "e/ee/eee" return the same, and "E/EE/EEE" return the same, I'd suggest these steps in sequence:
1a) In DateFormat(), remove the "e/E: Day in a week." bullet.
1b) In DateTimeFormat(), change "EEE" to "eee/EEE" and change "EEEE" to "eeee/EEEE".
1c) Copy the "eee/EEE" and "eeee/EEEE" bullets over to DateFormat() where "e/E" used to be.
2) f/F should be copied to DateTimeFormat() from DateFormat().
3) k/K should be _moved_ from DateFormat() to DateTimeFormat(). Since k/K are time-related, they serve no purpose on the DateFormat() doc. And k/K should be removed from DateFormat()'s History section.
4) Since k is "Hour in day (1-24)" and K is "Hour in am/pm (0-11)", they should be separate bullets on the DateTimeFormat() doc. Not grouped together as "k/K".
5) The "gg" should be copied to DateTimeFormat() from DateFormat(), except:
5a) The "Ignored. Reserved." should be removed from its description. They are not ignored.
5b) The "The following masks tell how to format the full date and cannot be combined with other masks:", in the description on DateFormat() needs moved out of that bullet, since it's actually the introductory text for the short/medium/long/full bullets beneath it. AND, actually, the short/medium/long/full section should be moved to the bottom, like it was on DateTimeFormat().
6) The "z and Z" masks should be copied to DateTimeFormat() from DateFormat().
7) The "X" bullets should be copied to DateTimeFormat() from DateFormat().
8) Masks "M and D" are only documented in the SimpleDateFormat doc. They work, so they should be documented in the DateFormat() and DateTimeFormat() docs.

Related URL: https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-c-d/DateTimeFormat.html

Attachments:

Comments: