Lua Style Guide ?

classic Classic list List threaded Threaded
96 messages Options
12345
Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
On 06/11/2017 09:18 AM, steve donovan wrote:
> On Sun, Jun 11, 2017 at 1:36 PM, Martin <[hidden email]> wrote:
> 6. Do we consciously conform to ldoc rules for comments?
>> May not, unless you are Steve Donovan.
>
> Heh. Well to be honest, all the @ soup can be irritating.

To be clear, I consider ldoc is absolutely adequate tool for "penlight"
library (and library is really good).

My point that not all code we write is public libraries with
documentation, thus no need to obligate authors to describe each
function with comment. Decision about built-in documentation is beyond
style, it's project-dependent design decision.

-- Martin

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
In reply to this post by Sean Conner
On Sun, Jun 11, 2017 at 4:15 PM, Sean Conner <[hidden email]> wrote:

> It was thus said that the Great Russell Haley once stated:
>> I'd like to find a way to generate the ldoc function headers from the file
>> automagically so I could fill in the details afterwards.
>
>   I think it might be relatively easy (I'm saying this without even
> bothering to try it) by using something like Luis' ltokenp (but perhaps
> something else that preserves comments) to parse Lua code to at least
> populate @function, @param, @local, and maybe even @raise (if it sees
> error()).
>
>   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

When I was first pined for an easier way to document things a few
months back, I thought of finding if ldoc could generate it. ltokenp
is a very attractive candidate. Alas, I have no time for such things.

Russ

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
In reply to this post by Martin
It was thus said that the Great Martin once stated:

> 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?
>
> 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>)"

  Actually, you have:

        1. function <name>(<args>)
        2. local function <name>(<args>)
        3. function <name>.<name>(<args>) -- defined on a table
        4. function <name>:<name>(<args>) -- also defined on a table
        5. function (<args>) -- anonymous function

> 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?

  As a first stab (and probably most useful) [1], just annotating style 1,
with maybe an option for style 2, would do [2].  Furthermore, if you could
determine if 2 was at the "global" level (that is, top level scope for a
file) and only do those would again be better.

> 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.

  I'm not sure what you are asking here.

  -spc (Hmm ... not so trival after all 8-P

[1] Just a gut feeling, no actual studies behind this.

[2] I did mention I didn't understand the full scope of this.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
In reply to this post by Martin
On Mon, Jun 12, 2017 at 5:24 AM, Martin <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
In reply to this post by Sean Conner
On Sun, Jun 11, 2017 at 11:10 PM, Sean Conner <[hidden email]> wrote:

> It was thus said that the Great Martin once stated:
>> 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?
>>
>> 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>)"
>
>   Actually, you have:
>
>         1. function <name>(<args>)
>         2. local function <name>(<args>)
>         3. function <name>.<name>(<args>) -- defined on a table
>         4. function <name>:<name>(<args>) -- also defined on a table
>         5. function (<args>) -- anonymous function
>
>> 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?
>
>   As a first stab (and probably most useful) [1], just annotating style 1,
> with maybe an option for style 2, would do [2].  Furthermore, if you could
> determine if 2 was at the "global" level (that is, top level scope for a
> file) and only do those would again be better.
>
>> 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.
>
>   I'm not sure what you are asking here.

Github would be my go-to.

Russ

>   -spc (Hmm ... not so trival after all 8-P
>
> [1]     Just a gut feeling, no actual studies behind this.
>
> [2]     I did mention I didn't understand the full scope of this.
>

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Dirk Laurie-2
In reply to this post by Russell Haley
2017-06-12 8:06 GMT+02:00 Russell Haley <[hidden email]>:

> When I was first pined for an easier way to document things a few
> months back, I thought of finding if ldoc could generate it. ltokenp
> is a very attractive candidate. Alas, I have no time for such things.

In my experience, the time needed to document a program can be
written off against the time saved when one day it becomes necessary
to revise the code. But I presume you mean you have no time for
learning autodocumenting tools.

I'll confess to having mixed feelings about those. They demand that
the author stay aware of how the LDoc version will look. It's so easy
and so useless to have an expanded version of the function header
with no additional information.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Russell Haley
On Sun, Jun 11, 2017 at 11:30 PM, Dirk Laurie <[hidden email]> wrote:

> 2017-06-12 8:06 GMT+02:00 Russell Haley <[hidden email]>:
>
>> When I was first pined for an easier way to document things a few
>> months back, I thought of finding if ldoc could generate it. ltokenp
>> is a very attractive candidate. Alas, I have no time for such things.
>
> In my experience, the time needed to document a program can be
> written off against the time saved when one day it becomes necessary
> to revise the code. But I presume you mean you have no time for
> learning autodocumenting tools.

I mean there are so many fun things available to us in open source
software, it's hard to pick where to apply my time. I made the mistake
of opening the README for ltokenp. :(

> I'll confess to having mixed feelings about those. They demand that
> the author stay aware of how the LDoc version will look. It's so easy
> and so useless to have an expanded version of the function header
> with no additional information.

I suspect you're right about 'ghost documentation'. But it could also
prove a useful tool for quickly adding documentation for that little
script someone wrote that everyone depends on and nobody knows how to
use? Again, the output to ldoc is going to get you a good way to where
I was thinking.

Russ

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
In reply to this post by Russell Haley
On Mon, Jun 12, 2017 at 1:00 AM, Russell Haley <[hidden email]> wrote:
> I'd like to find a way to generate the ldoc function headers from the file automagically so I could fill in the details afterwards.

It would be useful, though at least having a regular comment in front
of the functions would go a long way. The minimal translation would
just replace '--' with '---'  - just @-free doc comments.

Otherwise (as others have noted) there are wide variations in how
functions and tables are declared. LDoc does this, but the problem is
then constrained by 'follows doc comment'.

Any token parser could do this job, but man there are Special Cases!

Hisham and I once talked about the usefulness of this in the context
of LuaRocks.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
In reply to this post by Russell Haley
On 06/11/2017 11:15 PM, Russell Haley wrote:
> On Sun, Jun 11, 2017 at 11:10 PM, Sean Conner <[hidden email]> wrote:
>> It was thus said that the Great Martin once stated:
>>> 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.
>>
>>   I'm not sure what you are asking here.
>
> Github would be my go-to.

Yes, the question was how better represent such narrow tool. Probably
yes, github project is best option. No installation script, but you have
to call "lua <script_name> <params>" by hand.


On 06/11/2017 11:10 PM, Sean Conner wrote:

> It was thus said that the Great Martin once stated:
>> 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>)"
>
>   Actually, you have:
>
> 1. function <name>(<args>)
> 2. local function <name>(<args>)
> 3. function <name>.<name>(<args>) -- defined on a table
> 4. function <name>:<name>(<args>) -- also defined on a table
> 5. function (<args>) -- anonymous function

Looks like we're both incorrect. There are three ways of declaring
functions I know, yours cases 1. 3. and 4. may be united to
syntactically correct sample "t = {f = {}} function t.f:a() end". So
there are still three ways.

  name =  // alphanumeric word
  params = "(" list_of_parameters ")"  // not defined further
  local_function = "local" "function" <name> <params>  // (1)
  function_name = (<name> ".")* <name> [":" <name>]
  global_function = "function" <function_name> <params>  // (2)
  function_value = "function" <params>  // (3)


On 06/11/2017 11:14 PM, Russell Haley wrote:
> 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.

Thank you for usage cases. I see that tool to be practical should parse
both lua code and ldoc comments.

Is there a formal grammar for ldoc comments? (In particular is there any
difference between "short" and "long" doc block representation? Where
whitespaces matters?)

-- Martin

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

steve donovan
On Mon, Jun 12, 2017 at 7:34 PM, Martin <[hidden email]> wrote:
> Is there a formal grammar for ldoc comments? (In particular is there any
> difference between "short" and "long" doc block representation? Where
> whitespaces matters?)

There is no difference, really. But the various tags have slightly
different rules. It may be useful to write these up in convenient
summary form.

I still think that a useful starting point is a simple one-line
comment for each public item.  Which I don't think requires too much
brain really. (This is the approach taken by Golang - just plain old
comments, no markup. And yet people don't always do it.  Some don't do
it because they believe tests are automatically documentation.)

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Dirk Laurie-2
In reply to this post by steve donovan
2017-06-12 9:36 GMT+02:00 steve donovan <[hidden email]>:
> On Mon, Jun 12, 2017 at 1:00 AM, Russell Haley <[hidden email]> wrote:
>> I'd like to find a way to generate the ldoc function headers from the file automagically so I could fill in the details afterwards.
>
> It would be useful, though at least having a regular comment in front
> of the functions would go a long way. The minimal translation would
> just replace '--' with '---'  - just @-free doc comments.

This is more or less as much as ihelp [1] recognizes.

---    The docstring of a function
-- A comment block from the Lua code of a function, formatted in LDoc
-- style, like this block. The comments may come immediately before the
-- first line of the function or anywhere inside it.  All comments must
-- start at position 1 of their lines and the first comment must start
-- with at least three hyphens. For a very short function, the whole
-- code is used as the docstring.
--
-- Not available for functions defined from the terminal while running
-- the standalone Lua interpreter.

[1] https://github.com/dlaurie/lua-ihelp or `luarocks install ihelp`.

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
In reply to this post by Hisham
On 06/09/2017 11:37 PM, Hisham wrote:

> On 10 June 2017 at 03:02, Sean Conner <[hidden email]> wrote:
>>
>> It was thus said that the Great Dirk Laurie once stated:
>>> 4. Do we make big do ... end blocks in our code in order to
>>> restrict the scope of locals?
>>
>>   I do that quite often.  In fact, I'll do things like:
>>
>>         local somevar do
>>           -- code to do a bunch of stuff
>>           somevar = ...
>>         end
>>
>> to make it clear that there is some non-trivial initialization of a local
>> variable.
>
> [...] above example with odd indentation [...]

Concerning odd indentation. I've found nice ninja indentation trick in
one of World of Warcraft addon:

  if <cond> then do
  end
  [many_lines_of code]
  ...
  end

For someone not closely familiar with Lua syntax it appears that
[many_lines_of_code] logic belongs to main branch, not "if".

-- Martin

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Martin
In reply to this post by steve donovan
On 06/12/2017 12:42 AM, steve donovan wrote:

> On Mon, Jun 12, 2017 at 7:34 PM, Martin <[hidden email]> wrote:
>> Is there a formal grammar for ldoc comments? (In particular is there any
>> difference between "short" and "long" doc block representation? Where
>> whitespaces matters?)
>
> There is no difference, really. But the various tags have slightly
> different rules. It may be useful to write these up in convenient
> summary form.
>
> I still think that a useful starting point is a simple one-line
> comment for each public item.

The hard part as I see is not how to represent newly generated
documentation block but how to detect that ldoc block is already present
and parse it in this case. Is there a good place in code where I can see
how parsing is implemented?

I have a feeling that people want to use such tool in pre-commit pipe.
So it must preserve/modify all existing comments and add documentation
placeholders for functions which does not have them.

-- Martin

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Javier Guerra Giraldez
In reply to this post by Daurnimator
On 10 June 2017 at 07:43, Daurnimator <[hidden email]> wrote:
>> 2. Do we locally cache predefined globals?
>
> I used to, but not anymore unless there is a very tight loop: and then
> I cache in a local, not an upvalue.

^ this


--
Javier

Reply | Threaded
Open this post in threaded view
|

Re: Lua style guide ?

Sean Conner
In reply to this post by steve donovan
It was thus said that the Great steve donovan once stated:
> Hisham and I once talked about the usefulness of this in the context
> of LuaRocks.

  And?

  -spc (Inquiring minds want to know ... )

Reply | Threaded
Open this post in threaded view
|

Re: Lua Style Guide ?

Bulat Ziganshin
In reply to this post by Russell Haley
Hello Russell,

Wednesday, June 7, 2017, 12:51:12 AM, you wrote:

> My preference is to maximize the amount of information on a single
> screen. While 250 characters is very long, picking an arbitrary number
> of characters applicable to computing in 1981 is suboptimal.

Actually it's as old as 1928:
https://en.wikipedia.org/wiki/Punched_card#IBM_80-column_punched_card_format_and_character_codes


--
Best regards,
 Bulat                            mailto:[hidden email]


12345