Generate documentation for CFML scripted syntax and closures

Hi all,

I used to write CFML using only tag based syntax until now (for several
reasons related to ACF). Now that I’m moving to Luceee I decided to favor
scripted syntax for component and tag based for CFM pages. Thus I don’t
won’t use the CFSCRIPT tag in CFC files but directly write script (e.g
Inside component { … } or interface { … }.

My opinion is that scripted syntax would be better for future CFML. Tag
based syntax may longer be needed. But…guys this is just my personal
opinion :slight_smile:

Now I wonder how can I generate documentation (e.g By using something like
ColdDoc or another existing one) ?

Also I’ve been pleased that annotations seems to be supported when I use
closures. Is there a chance these will be extracted by an existing CFML
documentation generator ? I mean, will my closures documentation generated ?

I didn’t had time to test or search for this (I will later).

Thank you---------
Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

I looked at ColdDoc source and currently I have no way to include closures
annotations in the generated documentation.
Because some closures are not created until some specific block of code are
executed. Thus it seems a lot complicated…
Example :

/** Returns a closure but their documentation cannot be generated easily (without executing it). Otherwise "first" call this function "then" pass the returned value to getMetadata() */ public function function commentStyles(string style="todo") { if(arguments.style == "multipleLines") /** This closure returns a comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { return "/* " & arguments.stringExpr & " */"; }; else /** This closure returns a TODO comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { var multipleLines=commentStyles("multipleLines"); return multipleLines("TODO: " & arguments.stringExpr); }; } // Closures are not included in this dump writeDump(getMetadata(commentStyles)); // Although closure as some interesting documentation writeDump(getMetadata(commentStyles("todo")));--------- *Don't expect I'm "Desmond Miles". It's just a pseudonym ;-)*

On Tue, Mar 24, 2015 at 2:38 PM, One Lookup <@Desmond_Miles> wrote:

Hi all,

I used to write CFML using only tag based syntax until now (for several
reasons related to ACF). Now that I’m moving to Luceee I decided to favor
scripted syntax for component and tag based for CFM pages. Thus I don’t
won’t use the CFSCRIPT tag in CFC files but directly write script (e.g
Inside component { … } or interface { … }.

My opinion is that scripted syntax would be better for future CFML. Tag
based syntax may longer be needed. But…guys this is just my personal
opinion :slight_smile:

Now I wonder how can I generate documentation (e.g By using something like
ColdDoc or another existing one) ?

Also I’ve been pleased that annotations seems to be supported when I use
closures. Is there a chance these will be extracted by an existing CFML
documentation generator ? I mean, will my closures documentation generated ?

I didn’t had time to test or search for this (I will later).

Thank you


Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

What are you trying to achieve,to document the return type of the function?
If so you can use the @return annotation. However, this is in our fork now
since we took over ColdDoc from Mark:
https://github.com/Ortus-Solutions/ColdDocOn Wednesday, March 25, 2015 at 3:39:19 AM UTC-7, Desmond Miles wrote:

I looked at ColdDoc source and currently I have no way to include closures
annotations in the generated documentation.
Because some closures are not created until some specific block of code
are executed. Thus it seems a lot complicated…
Example :

/** Returns a closure but their documentation cannot be generated easily (without executing it). Otherwise "first" call this function "then" pass the returned value to getMetadata() */ public function function commentStyles(string style="todo") { if(arguments.style == "multipleLines") /** This closure returns a comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { return "/* " & arguments.stringExpr & " */"; }; else /** This closure returns a TODO comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { var multipleLines=commentStyles("multipleLines"); return multipleLines("TODO: " & arguments.stringExpr); }; } // Closures are not included in this dump writeDump(getMetadata(commentStyles)); // Although closure as some interesting documentation writeDump(getMetadata(commentStyles("todo")));

Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

On Tue, Mar 24, 2015 at 2:38 PM, One Lookup <onel...@gmail.com <javascript:>> wrote:

Hi all,

I used to write CFML using only tag based syntax until now (for several
reasons related to ACF). Now that I’m moving to Luceee I decided to favor
scripted syntax for component and tag based for CFM pages. Thus I don’t
won’t use the CFSCRIPT tag in CFC files but directly write script (e.g
Inside component { … } or interface { … }.

My opinion is that scripted syntax would be better for future CFML. Tag
based syntax may longer be needed. But…guys this is just my personal
opinion :slight_smile:

Now I wonder how can I generate documentation (e.g By using something
like ColdDoc or another existing one) ?

Also I’ve been pleased that annotations seems to be supported when I use
closures. Is there a chance these will be extracted by an existing CFML
documentation generator ? I mean, will my closures documentation generated ?

I didn’t had time to test or search for this (I will later).

Thank you


Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

In my example the closure is the return value. But what if the closure is
not a return value (e.g a local variable) ?
What I want is a tool that is able to extract closure’s
documentation/annotation from code (and may generate documentation with
those data). Even if it’s possible, it’s useless in real cases but that was
the idea :slight_smile:

Of course this can always be directly written in the parent’s documentation
(e.g using @return in my example). And that’s the way it should be done
(and moving the closure somewhere else means moving the comments also).
Because seperating closure’s annotation but generating it in it’s closest
parent’s documentation makes no sense in real cases (i.e the goal is to
write doc not to complicated it).
There’s a similar situation with Java and anonymous inner class (their doc
comments are simply ignored and no one can extract them).

Anyway I would be pleased if a tool does parse the code and tells me : “Hey
here’s your function description. See here are some description about some
closure I’ve found in it”.

Regards,On Thursday, March 26, 2015 at 5:05:15 PM UTC+1, Luis Majano wrote:

What are you trying to achieve,to document the return type of the
function? If so you can use the @return annotation. However, this is in
our fork now since we took over ColdDoc from Mark:
https://github.com/Ortus-Solutions/ColdDoc

On Wednesday, March 25, 2015 at 3:39:19 AM UTC-7, Desmond Miles wrote:

I looked at ColdDoc source and currently I have no way to include
closures annotations in the generated documentation.
Because some closures are not created until some specific block of code
are executed. Thus it seems a lot complicated…
Example :

/** Returns a closure but their documentation cannot be generated easily (without executing it). Otherwise "first" call this function "then" pass the returned value to getMetadata() */ public function function commentStyles(string style="todo") { if(arguments.style == "multipleLines") /** This closure returns a comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { return "/* " & arguments.stringExpr & " */"; }; else /** This closure returns a TODO comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { var multipleLines=commentStyles("multipleLines"); return multipleLines("TODO: " & arguments.stringExpr); }; } // Closures are not included in this dump writeDump(getMetadata(commentStyles)); // Although closure as some interesting documentation writeDump(getMetadata(commentStyles("todo")));

Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

On Tue, Mar 24, 2015 at 2:38 PM, One Lookup onel...@gmail.com wrote:

Hi all,

I used to write CFML using only tag based syntax until now (for several
reasons related to ACF). Now that I’m moving to Luceee I decided to favor
scripted syntax for component and tag based for CFM pages. Thus I don’t
won’t use the CFSCRIPT tag in CFC files but directly write script (e.g
Inside component { … } or interface { … }.

My opinion is that scripted syntax would be better for future CFML. Tag
based syntax may longer be needed. But…guys this is just my personal
opinion :slight_smile:

Now I wonder how can I generate documentation (e.g By using something
like ColdDoc or another existing one) ?

Also I’ve been pleased that annotations seems to be supported when I use
closures. Is there a chance these will be extracted by an existing CFML
documentation generator ? I mean, will my closures documentation generated ?

I didn’t had time to test or search for this (I will later).

Thank you


Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

Well in that case we do love pull requests :slight_smile:

Luis Majano
CEO
Ortus Solutions, Corp
www.ortussolutions.comP/F: 1-888-557-8057

Direct: (909) 248-3408

ColdBox Platform: http://www.coldbox.org

ContentBox Platform: http://www.gocontentbox.org

Linked In: http://www.linkedin.com/pub/3/731/483

Social: twitter.com/ortussolutions | twitter.com/coldbox | twitter.com/lmajano | twitter.com/gocontentboxOn Fri, Mar 27, 2015 at 2:55 AM, Desmond Miles <@Desmond_Miles> wrote:

In my example the closure is the return value. But what if the closure is
not a return value (e.g a local variable) ?
What I want is a tool that is able to extract closure’s
documentation/annotation from code (and may generate documentation with
those data). Even if it’s possible, it’s useless in real cases but that was
the idea :slight_smile:
Of course this can always be directly written in the parent’s documentation
(e.g using @return in my example). And that’s the way it should be done
(and moving the closure somewhere else means moving the comments also).
Because seperating closure’s annotation but generating it in it’s closest
parent’s documentation makes no sense in real cases (i.e the goal is to
write doc not to complicated it).
There’s a similar situation with Java and anonymous inner class (their doc
comments are simply ignored and no one can extract them).
Anyway I would be pleased if a tool does parse the code and tells me : “Hey
here’s your function description. See here are some description about some
closure I’ve found in it”.
Regards,
On Thursday, March 26, 2015 at 5:05:15 PM UTC+1, Luis Majano wrote:

What are you trying to achieve,to document the return type of the
function? If so you can use the @return annotation. However, this is in
our fork now since we took over ColdDoc from Mark:
https://github.com/Ortus-Solutions/ColdDoc

On Wednesday, March 25, 2015 at 3:39:19 AM UTC-7, Desmond Miles wrote:

I looked at ColdDoc source and currently I have no way to include
closures annotations in the generated documentation.
Because some closures are not created until some specific block of code
are executed. Thus it seems a lot complicated…
Example :

/** Returns a closure but their documentation cannot be generated easily (without executing it). Otherwise "first" call this function "then" pass the returned value to getMetadata() */ public function function commentStyles(string style="todo") { if(arguments.style == "multipleLines") /** This closure returns a comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { return "/* " & arguments.stringExpr & " */"; }; else /** This closure returns a TODO comment in a multi-line format @stringExpr The content for the returned comment */ return function(required string stringExpr) { var multipleLines=commentStyles("multipleLines"); return multipleLines("TODO: " & arguments.stringExpr); }; } // Closures are not included in this dump writeDump(getMetadata(commentStyles)); // Although closure as some interesting documentation writeDump(getMetadata(commentStyles("todo")));

Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:

On Tue, Mar 24, 2015 at 2:38 PM, One Lookup onel...@gmail.com wrote:

Hi all,

I used to write CFML using only tag based syntax until now (for several
reasons related to ACF). Now that I’m moving to Luceee I decided to favor
scripted syntax for component and tag based for CFM pages. Thus I don’t
won’t use the CFSCRIPT tag in CFC files but directly write script (e.g
Inside component { … } or interface { … }.

My opinion is that scripted syntax would be better for future CFML. Tag
based syntax may longer be needed. But…guys this is just my personal
opinion :slight_smile:

Now I wonder how can I generate documentation (e.g By using something
like ColdDoc or another existing one) ?

Also I’ve been pleased that annotations seems to be supported when I use
closures. Is there a chance these will be extracted by an existing CFML
documentation generator ? I mean, will my closures documentation generated ?

I didn’t had time to test or search for this (I will later).

Thank you


Don’t expect I’m “Desmond Miles”. It’s just a pseudonym :wink:


You received this message because you are subscribed to a topic in the Google Groups “Lucee” group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/lucee/P0HNudSr4tM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to lucee+unsubscribe@googlegroups.com.
To post to this group, send email to lucee@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/lucee/b5b5aa10-559c-4bde-a218-e8435350a2ad%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.