Hi there, I am going through a spectacularly large component that has spectacularly large and complex functions. I would just love to document the whole thing as

"Dragons live here : do not EVER consider editing or even trying to understand anything in here."

But of course this isn't helpful for anyone. The CFC is entirely cfscript. (Side quest : is there a way to display a literal AT symbol in slack - Eg. AT:hint complains about having multiple possible matches?) Now, I know I can create anything I like as an annotation,

@mybullshitannotation this is some some text

However - I can't seem to find a list of the ones that I can use that have a "special" meaning. That is - is there a list that would contain

returnFormat, returnType, hint, etc

Or is simply a one-to-one for the tag attributes from the cffunction docs here? Are there any differences? Are they documented anywhere? - if not I feel a doc PR coming along. More specifically - to my current need - how do I annotate an argument in cfscript? I know that the following provides the "hint";

@argumentOne This a hint

But... how do I annotate for; the datatype of the argument? if it is required? or is Just "free text" for arguments as a result of Lucee treating annotations differently to ACF (Lucee believes an annotation is just a comment and should not effect code operation , (which I like BTW). So it would seem nonsensical to have special handling of argument attributes in annotations? I don't mind, either way - I just can't find anything specifically about it in the docs. As always thanks!

here's what we use:

/**
     * Takes a query and returns it as an array of structs; allows forcing key case of nested structs and htmlencoding of values
     * 
     * @data query             	    the input query to convert to array of structs
     * @forcecase string        	?: NATURAL | UPPER | LOWER when specified, is the case to forcibly convert column names when creating struct keys
     * @forJson boolean         	?: when true will do some additional escaping which may trip some json conversions
     * @htmlEncode  boolean     	?: when true, will htmlencode values before moving to array	 
     * 
	 * @see safeFormat
	 * 
     * @return array            the array of structs representing the original query
     */
    public array function queryToArray(
        required query data, 
        string forcecase="natural", 
        boolean forJson="false", 
        boolean htmlEncode="false"
    ) output=false {
        
        var results = [];

        ...

    }

Thanks @websolete I can feel @Adam Cameron looking over my shoulder - going "tsk tsk tsk"... I probably should have just tried some testing! What I have found, via; https://trycf.com/gist/f7ead43791f2f85dd5c07179db06d745/lucee5?theme=monokai If you provide an argument hint as an annotation AND NOT in the function declaration - it populates the function metadata correctly. If you provide an argument hint as an annotation AND in the function declaration - the function declaration's version of the hint, wins. You can ONLY define an argument's HINT as an annotation. required, type, output, cachedWithin, etc CANNOT be set via an annotation. The following argument annotation does NOT set myArg1 's type to query. Merely serving as a visual aid - if you don't look at the function's signature. Subsequently, if you ever change an argument's type in the function, your annotation (hint) will be wrong.

@myArg1 query the input query to convert to array of structs

I can see a few documentation updates in my future. The Lucee docs in one place state everything as I have tested - but also says:

This notation and thus the functionality behind it means, that comments are affecting the code's behaviour, which Lucee Server does NOT support. The following example will throw a compiler error:

/**
* @returntype string
*/
public int function test(arg1) {
}

Which is wrong: I tested it. It does NOT throw an error. It is just ignored - as stated elsewhere on the same page.

@gavinbaumanis

int

is not a returntype in CFML. Unless you have a int.cfc I guess. A better test of what you are trying to see is perhaps this:

/**
* @returntype numeric
*/
public function test(arg1) {
    return "hi"
}

test()

CF:

The value returned from the test function is not of type numeric

Which is what I'd expect. Lucee:

[nothing]

On CF if one has both the explicit type on the function signature and the annotation as well, then the one on the function signature wins, but there is no error to indicate there is a conflict between the two if they are different. There probably should be.

Hi Adam, That quote is direct from the Lucee docs and reads - to me at least - like it saying that code example when run on Lucee will throw an error. But of course doesn't. So the docs are wrong.

"I see".