Documentation Questions

[shawnoden]

I'm documenting the D functions, and I came across two issues that I need clarification on.

1. When documenting optional arguments, Adobe does it like required [,opt2] [,opt3], but Lucee does it like `required [, opt2 [,opt3]]. Do we have a preference which way we label optional arguments?

2. When documenting Member Functions, there are some member functions that have been shortened in CF2018, for instance dateTimeFormat(). Do we stick with the CF11+ method of mydate.dateTimeFormat() or should we also show the shorter CF2018+ method of mydate.format()? And if we show both, how do we indicate the second CF2018+ member function?

3. There were actually 3 questions. Speaking of dateTimeFormat(), the sheet (NamedParametersColdFusion2018.pdf) from Issue #898 shows dateTimeFormat(date, timezone [,mask]). timezone is an optional argument, and I think it should be listed as such. Should I correct obvious incorrect named parameter issues like this, or should I stick with what's on the sheet, which is supposed to be Adobe-official?

[shaedrich]

1. Strictly speaking required [,opt2] [,opt3] means that the optional parameters do not depend on each other so their order as well as presence or absence doesn't affect the others. so required [,opt2] would be valid as well as required [,opt3]. Whereas required [, opt2 [,opt3]] means that opt3 can only been passed at the third position and only if opt2 is passed as well. So I think, we should stick by the one which matches the method's param handling.
2. Hmmm… That's up to @pfreitag to decide in the final analysis, but I would say, just add the newer one to the engine notes. The long format works in both CF11+ and CF2018+, right?
3. This question is in turn a question for @KamasamaK. Was this behavior changed in CF2018+? If this was and is optional, it should be indicated in the syntax. If this changed, it should be indicated in the engine notes. You can test with trycf.com if the Adobe pdf is wrong and if it is, it might be worth a discussion if that should be mentioned in the engine notes as well…

[KamasamaK]

3. I'm not surprised there are mistakes. There's no way they changed the order of the parameters like that in ACF2018. Just test if you're unsure. When I posted that PDF, it was supposed to be used primarily as a resource for the new parameter names, and knowing Adobe there are probably even a few mistakes there too.

[pfreitag]

1. See @shaedrich's comment above
2. Let's add the shorer/newer one into the engine notes, assuming the long one still works
3. Agree with @KamasamaK - whatever is correct should be what is documented, sometimes Adobe makes mistakes in the documentation, in those cases they will typically fix the docs, not the implementation to match. You can also ping saghosh (Saurav Ghosh from Adobe) on slack to see what he things.

[shawnoden]

@shaedrich and @KamasamaK

RE: 1) That makes a lot of sense. I like the way Lucee's page looks ( required [,opt1 [,opt2]] ) and I do think they are probably the most right. I don't know what I was looking at yesterday, but apparently today Adobe is showing required [,opt1 , opt2], implying both are required together and essentially saying the same thing as Lucee. Does CFDocs prefer one way to the other. Also, just tested CF2018 and found out that if I pass the parameter name, it will take the second optional argument without the first (DateTimeFormat(datetime=t,timezone="EST")), though technically I guess the first optional argument is included, it's just defaulted. And should I include a reminder that these named parameters aren't available for member functions yet, but are planned to be included?

RE: 2) I'm pretty sure I added the alternate syntax into the notes on the ones I've already come across. I was just curious if we had a method to input multiple options for the member functions. I'll keep doing what I'm doing.

RE: 3) I tested it and it behaves like originally specified and like Adobe documented on their site. I think the PDF is an error. I know that it was said earlier that the PDF was technically the most truthful, but I just wanted to make sure that this was one of those cases where the PDF was wrong and I should document correct behavior.

[shawnoden]

And one more question. When the named parameters for Adobe and Lucee differ ( ie dateTimeFormat() > Adobe=date, Lucee=datetime ) should I go with the Adobe version in syntax and note the other? And what would be the best way to note the other? In param description?

[KamasamaK]

@shawnoden That was addressed in #898. The ACF parameter names were added as aliases in Lucee, so it's fine if the primary name differs. I don't think it's necessary to document the other names as well.

[shawnoden]

@KamasamaK "That was addressed in #898." << That's actually the one I'm working on. It helps if I go back and read a bit deeper. :-) What about functions like day() that has one optional Lucee argument [,timezone] but has no optional arguments in ACF? Do we note the Lucee argument somewhere?

[shawnoden]

I'm full of questions. Another one I ran into. dayOfWeekAsString() parameters changed in CF2018. Adobe renamed day_of_week (<=2016) to dayofweek in CF2018+. Since 2016 didn't really do named params, I'm guessing I should go with the 2018 version (`dayOfWeek'). I tested and both work in Lucee 4.5 and 5 when passed as the parameter name. If I come across a similar situation, I go with the CF2018 version, correct?

[pfreitag]

@shawnoden correct - use the CF2018 name since named params were not supported in prior versions.

[shawnoden]

Another question. The functions encrypt and decrypt have optional arguments that are also dependent on other arguments, and arguments in the same position that have different names depending on the situation. Specifically iv and salt, which used to be IVorSalt prior to CF2018. With named parameters, CF2018 no longer accepts IVorSalt and only takes 'ivorsaltdepending on other options. Plus, additional crypto libraries can be installed. How should I document that argument 5 ofencrypt/decryptcan be eitherivorsalt? And if I list both as separate structs for params`, will it break anything?

[KamasamaK]

@shawnoden As stated in my comment in #898, this would be addressed with #529.