Generate documentation for CFML scripted syntax and closures

[One Lookup]

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 :-)

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 ;-)

[One Lookup]

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 :

<cfscript>
	/** 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")));
</cfscript>

---------

Don't expect I'm "Desmond Miles". It's just a pseudonym ;-)

[Luis Majano]

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

[Desmond Miles]

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 :-)

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,

[Luis Majano]

Well in that case we do love pull requests :)

Luis Majano
CEO
Ortus Solutions, Corp
www.ortussolutions.com

P/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/gocontentbox

--
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+un...@googlegroups.com.
To post to this group, send email to lu...@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.