cfdocs
cfdocs copied to clipboard
foundeo
Ensure parameter names match ColdFusion 2018+
This refers to the parameter names used in NamedParametersColdFusion2018.pdf
I think these are mostly good, but this issue will be a reminder for me (or anyone else) to go through all of them to ensure that they match. Lucee already supported this feature, and they have already ensured via LDEV-1806 that they at least have aliases for the ColdFusion names. Because of this, we should go with the more restrictive name.
I've started this and I've found there to be more discrepancies than I expected. Also, there are discrepancies between the PDF and the web docs, so I'm siding with the PDF for now until I can get confirmation. Also, multiple signatures (#529) is complicating it, so for now I'm keeping with combining the params e.g. value or callback.
@KamasamaK
I just saw this and noticed a couple of discrepancies with things I've just PRed here. I'll go back through and update mine. Also, did you get official confirmation on which version of the Named Param arguments are official?
I'll also start going through these. Have you done A-B and C, or have you done others as well? Any suggestions on which to start with? Is anyone else actively working on this?
@shawnoden You are correct that I've only done up to C. I've been meaning to get back to this, but I have not done any after C that are pending. A few months ago, I asked Saurav -- the person who works on ColdFusion documentation -- and was told that the PDF is correct and that the web pages would be updated to match. Unfortunately, it doesn't seem like this is being done in a timely manner.
OK, as I get time, I'll work on these. I'll post the letter I'm working on here both when I start and when I finish so we don't step on each other.
For syntax, if a function has an optional parameter, should we signify that in both the syntax block and in the params block? ie {...."syntax":"myFunction(required1,[optional1])".... params":[ "name":"optional1",......,"required":false, ....]} or {...,"syntax":"myFunction(required1,optional1)"...} << So put in square brackets or not?
The square brackets seems to be the preferred way to denote this, but the required value in params is most important. We could even dynamically generate the syntax string with sufficient information in params.
I'll use square brackets, then. That seems to be the case in almost every piece of code documentation I've seen, and it makes it very easy to see which attributes are required and which are optional. I just didn't want it to break any of the IDEs.
I am working on the "D" functions, and I'm trying not to add too many files and changes to each PR I'll make so that I don't make whoever reviews these pull their hair out. I initially started by going through these and cleaning up any discrepancies in the description or adding an additional example, especially to clarify the member function changes to some of these older functions. But I'm finding that, after reconciling both ACF and Lucee documentations to make sure I note any differences, I've only made it through 5 so far. I didn't realize so many functions had been added to CFML over the years. I understand what you said about this being a much bigger task than you initially thought. I'm thinking I should just follow this Issue and only update the parameter names, then create a new issue for Function Cleanup and go back later to do that cleanup. Or should I just continue to slowly plow through these?
Back to my changes here. I'm still cleaning up some of these entries as I'm going through them, and I had a question. I know I've asked similar in another issue, but I don't like using a "-" for an unordered list. It just doesn't look as clean as an actual list delimiter. Is there something in the parsing that will function as a list delimiter, like "-" would in Markdown? I apparently can insert li tags to format the list, but I don't think that's the right approach either. What is the preferred method to make a delimited list?
See #883 for discussion on formatting descriptions. This issue is just about changing parameter names.
Yeah, I started off with just changing parameter names, but, since I was already there, began fixing formatting and other issues as I was going through the functions. I do agree that they should be two separate issues, and my plan was to finish the block that I'm doing and then switch to working 2 different issues. If needed, I can roll back everything but the parameter name changes and put the formatting changes into another issue. Whatever is needed.
I have completed Parameter Names for the D Functions. I'll doublecheck those and submit a PR for the last 2 batches of them. Then I'll start on the E functions.
I pretty quickly realized that if I also did a Boy Scout Leave It Better Than You Found It on the pages and cleaned up examples and such, then:
- It would take a long time just to make it through the Ds.
- It was well out of the scope of this original issue (898).
That said, I'm going to stick to parameter names for the rest. After I finish these, I'll submit another issue to go back and clean up Descriptions and Examples.
I've been slacking. I've got E Functions done through Encrypt(), and I'll finish up the other Es. Then I'll tackle the next ones in line.
F functions are complete. fiileUploadAll() still needs some refinement and verification. The parmas listed in Adobe's pdf don't match the ones listed on either the Adobe page (https://helpx.adobe.com/coldfusion/cfml-reference/coldfusion-functions/functions-e-g/fileuploadall.html) or the Lucee page (https://docs.lucee.org/reference/functions/fileuploadall.html), but they do match in concept. I'll verify those param names when I get to a machine that can run CommandBox.
Also, re: fileUploadAll() : Lucee has an extra param, acl that is used for S3 resources. ACF doesn't have this param. How do we document params that are extra to Lucee? Do we leave it off the definition but add it in the descriptions with a Lucee marker?
H is done. I skipped G for now since there are a lot of them. So I believe that makes this Issue done through H functions, except G.