Lua comment --~

Question

I know LuaDoc uses "---" on the first line of comments like this:

--- an example function
-- @param a parameter a desc
-- @param b parameter b desc
function f (a,b)
   --code
   --code
end

However I see this in the beginning of comments:

--~ comment for a function
function f (a,b)
   --code
   --code
end

does it have special meaning?

Answer 1

The SciTE editor distributed with Lua for Windows uses this as a marker for their automatic commenting facility.

Try selecting a block and select 'Edit/Block Comment or Uncomment' from the menu, it adds --~ to the front of the line. Likewise Uncomment removes it. However if you just have --, then select the menu option it doesn't recognize this as a comment, and adds it's own comment --~.

I've assumed that it has no significance, it's just an easy marker for the SciTE editor to parse. As noted by RBerteig there is no special significance of --~ to LuaDoc, and it is otherwise just a comment like any other to Lua itself.

Answer 2

Apparently not.

Inspection of the implementation of the version of LuaDoc included in Lua for Windows reveals that there appears to be no case where a comment of the form --~ is noticed by its parser as anything other than an additional line of a LuaDoc comment block that began with a --- comment.

That is, it is possible that a comment beginning with --~ can continue a documentation comment block, but not introduce a document comment block.

Without additional context, it difficult to guess whether this was a typo or a way to leave a nearly correct LuaDoc comment that will be ignored until the tilde is changed to a dash. The latter interpretation is plausible if the context made the function marked that way appear to be a boiler plate template. In that case, when the template is copied and pasted for use, one would be expected to fix up the comment to make it visible to subsequent runs of LuaDoc.