Re: Lua style guide ?

[Russell Haley <russ.haley@...>]

On Mon, Jun 12, 2017 at 5:24 AM, Martin <eden_martin_fuhrspam@gmx.de> wrote:
> On 06/11/2017 04:15 PM, Sean Conner wrote:
>>   For example, this function:
>>
>>       function encode(value,sref,stref)
>>         local res = ""
>>
>>         if stref and not stref.SEEN then
>>           res = TAG._stringref(nil,nil,stref)
>>         end
>>
>>         return res .. __ENCODE_MAP[type(value)](value,sref,stref)
>>       end
>>
>> such a tool could return:
>>
>>       --- Placeholder
>>       -- @function encode
>>       -- @param value
>>       -- @param sref
>>       -- @param stref
>>       -- @return
>>       function encode(value,sref,stref)
>>       ...
>>
>>   -spc (I don't understand the full scope of this, so of course it must be
>>       trivial! 8-P
>
> Hmm, as experiment I can create a breed of lua code formatter which
> produces output with such autogenerated comments. But is there really
> need for this?

At $work I have been going back over old C++ code that I don't know
and one of the most useful ways I have found to get a grip on it is to
write my own notes, and then create and or fix the documentation and
inspect the doxygen output. I can then compare to see how out to lunch
the current understanding of the code is. I see two use cases for such
an aforementioned tool:

1) undocumented code: Generate the headers to eliminate the
mental/time barrier of "having to write all that". It would be far
easier to fill it in then having to transcribe the @ soup.
2) To check the relevance or changes to existing comments. I would see
such a parser "commenting out" entries that are no longer relevant and
adding new ones, as well as being able to generate the headers in a
seperate file.

Thinking of it, I suppose if I could capture the output from ldoc? To the lab!

Russ

> Function in Lua may be defined in three ways:
>
> 1. "local function <name> (<args>)" //<name> can't contain ":" syntel
> 2. "function <name> (<args>)"
> 3. "function (<args>)"
>
> Most obscure case is (3). It is often used as expression for sort() or
> gsub(). Do you have a good heuristic how do decide emit/not_emit header
> for function, given annotated syntax tree of source?
>
> And by the way, are there good ways to test such formatter? Creating yet
> another rock with name like "lcf.experiments" looks like a bad idea.
>
> -- Martin
>