Deprecated in favor of

[shaedrich]

Would it make sense to link explicitly to the recommended tag/function (maybe use a new key for this) when a tag/function is deprecated?

[pfreitag]

so a good example of this is HTMLEditFormat is deprecated in favor of encodeForHTML... In the engine notes it mentions encodeForHTML so it is auto linked, but it might make sense to add something to engine struct with something like obsoletedBy: "encodeForHTML" ?

Open to other suggestions about how to represent that

[shaedrich]

I guess, that's a good way to do.

[KamasamaK]

This is a good idea, but what about if there are multiple replacements? For example, htmlEditFormat was brought up as being obsoleted by encodeForHTML, but there's also encodeForHTMLAttribute.

[shaedrich]

Then we could simply pass an array. Where's the problem?

[KamasamaK]

@shaedrich Who said there was a problem? I said it was a good idea. We are here to find and agree upon the best way to implement this solution.

[shaedrich]

@KamasamaK I didn't want to affront you. I just wanted to say: "Then easily change datatype from string to array. I don't see any problems in doing this"

[AnthonyKolka]

I just had this question for cffileupload. The answer is FileUpload.

[pfreitag]

I'm ok with adding obsoletedBy:[] to the json schema, there are actually a bunch of examples I think think of...

• parameterExists -> isDefined
• htmlEditFormat -> encodeForHTML, encodeForHTMLAttribute
• urlEncodedFormat -> encodeForURL
• cfgraph -> cfchart
• cfdocument -> cfhtmltopdf

[KamasamaK]

I think "obsolete" is too strong for some of these. For example, there are differences between cfdocument and cfhtmltopdf that mean there are still valid reasons to use cfdocument. Also, while encodeForURL is perfectly fine for URL parameters, I've had issues and needed to revert back to urlEncodedFormat when used for path segments -- it's possible I'm just doing something wrong here.

[pfreitag]

I agree with you @KamasamaK - any suggestions for a better word would be welcome

[shaedrich]

Well, I don't think "replacedBy" would be better, but maybe "discouragedBy"?

[KamasamaK]

I think some variation of "discourage"/"encourage" or "recommend" is lax enough for more general use. The first thing that comes to mind is discouragedInFavorOf, but that's too wordy 😄. The next thing that comes to my mind is recommendedReplacements, which isn't short either. I do not have a knack for naming things tersely -- just ask CFLint.

[shaedrich]

recommendedReplacements isn't bad...

[KamasamaK]

Ok, I will look into modifying the schema. I have an inclination to use camelCase, but the properties I've introduced until now follow the lead of minimum_version with snake_case so I will call it recommended_replacements.