Documenting Lua Code Like a Pro

[Charles_McKeever]

Here’s a Lua documentation tip from Rene Aye @ DevilSquid Entertainment.

http://devilsquid.com/how-to-get-a-better-coder-by-documenting-lua-code-like-a-pro/

[DevilSquid_Rene]

Placing this in the Getting Started forum makes sense. 

Thank you Charles.

[DevilSquid_Rene]

I found out that in some situtions the LDoc syntax alone is not flexible enough.

(in example options tables as function paramter).

I wrote a second article about adding Markdown support to LDoc so that more complicated code situations can be documented as well.

Here is the link: http://devilsquid.com/why-and-how-to-add-markdown-support-to-gain-more-power-to-your-ldoc-syntax/

[tonygod]

Hi, René.  First, I want to thank you for posting about LDoc on the Corona forums.  I had been loosely commenting my code and not really documenting it properly, mostly due to laziness.  After seeing your post, I started to play with LDoc and it seems like a good solution for me and has motivated me to properly comment/document my code.  So, thanks.

I have a couple of issue, I am hoping you can help out with:

1. When I am trying to use LDoc in a bash script, it seems to process my source files, but then fails at the end with this message:  

Could not copy /tmp/ldoc/ldoc.css to /doc/ldoc.css

/tmp/ldoc/ldoc.css exists, but /doc is not the correct directory.  I can’t figure out why it is trying to put it there instead of the directory I am specifying with the -d parameter.  Here’s my bash script:

#!/bin/sh project\_base\_name=Hoppy Naut project\_path=~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/ ~/LDoc/ldoc.lua $project\_path -p "$project\_base\_name" -d $project\_path/doc/ -f 'markdown'

I am not as familiar with bash as I am batch/powershell, so I probably don’t understand something about the way bash and the ldoc.lua script work together.

There is no problem if I just run the same command from the terminal, replacing the variables with  the values I am specifying:

~/LDoc/ldoc.lua ~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/ -p "Hoppy Naut" -d ~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/doc -f 'markdown'

Hopefully you see something obvious that I am doing wrong.

2. It seems ldoc doesn’t handle tables like the below.  Do you have any suggestions on how these can be written/formatted to be handled by ldoc?

   — Table full of other tables and stuff myTable = { subTableA = { someStrings = { “this is a string”, – first string “here is another string” – second string } }, subTableB = { someStrings = { “this is a string”, – first string “here is another string” – second string } }, }

Thanks for taking the time to read.   I look forward to hearing back from you.

Best regards,

Tony Godfrey

[DevilSquid_Rene]

Hi Tony,

great to hear that the article moved you to try LDoc. I’m assured this helps on the long run. 

I’m pretty sure I had the same error regarding the CSS files. Just can not remember how I solved it.

Let me check the settings you use. I will get back to you.

René

[DevilSquid_Rene]

I’m wondering: shouldn’t the values in your bash script be in quotes like this?

1. project_base_name=“Hoppy Naut”

[DevilSquid_Rene]

Are you using a customized CSS file?

[DevilSquid_Rene]

I had success with the following LDoc syntax to document tables with subtables:

------------------------------------------- -- A test to document tables with LDoc -- @module TableTest ------------------------------------------- -- The Person table stores information about the persons. -- -- @table Person -- @field name The name of the person -- @field age The age of the person -- local Person = { name = "John Doe", age = 40, ------------------------------------------- -- The Hobbies of that Person -- -- @table Person.hobbies -- @field name The name of the hobby -- @field spent How much the person has spent on that hobby -- hobbies = { { name = "Painting", spent = 175 }, { name = "Cycling", spent = 2034 }, } }

When I take away the @module options from the first lines, I get some errors. So make sure the files does have a @module.

I don’t know if this matches your table structure, but maybe you can adopt to yours?

[tonygod]

Thanks for all the tips, DevilSquid.  It took me a while to get back around to play with the table again, but your suggestion to use @table and @field works just fine.

I still haven’t managed to figure out what is wrong with the bash script, but I have a workaround that is working okay for me now.

Best regards,

Tony

[DevilSquid_Rene]

Placing this in the Getting Started forum makes sense. 

Thank you Charles.

[DevilSquid_Rene]

I found out that in some situtions the LDoc syntax alone is not flexible enough.

(in example options tables as function paramter).

I wrote a second article about adding Markdown support to LDoc so that more complicated code situations can be documented as well.

Here is the link: http://devilsquid.com/why-and-how-to-add-markdown-support-to-gain-more-power-to-your-ldoc-syntax/

[tonygod]

Hi, René.  First, I want to thank you for posting about LDoc on the Corona forums.  I had been loosely commenting my code and not really documenting it properly, mostly due to laziness.  After seeing your post, I started to play with LDoc and it seems like a good solution for me and has motivated me to properly comment/document my code.  So, thanks.

I have a couple of issue, I am hoping you can help out with:

1. When I am trying to use LDoc in a bash script, it seems to process my source files, but then fails at the end with this message:  

Could not copy /tmp/ldoc/ldoc.css to /doc/ldoc.css

/tmp/ldoc/ldoc.css exists, but /doc is not the correct directory.  I can’t figure out why it is trying to put it there instead of the directory I am specifying with the -d parameter.  Here’s my bash script:

#!/bin/sh project\_base\_name=Hoppy Naut project\_path=~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/ ~/LDoc/ldoc.lua $project\_path -p "$project\_base\_name" -d $project\_path/doc/ -f 'markdown'

I am not as familiar with bash as I am batch/powershell, so I probably don’t understand something about the way bash and the ldoc.lua script work together.

There is no problem if I just run the same command from the terminal, replacing the variables with  the values I am specifying:

~/LDoc/ldoc.lua ~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/ -p "Hoppy Naut" -d ~/Documents/source/Hoppy\ Naut/Hoppy\ Naut/doc -f 'markdown'

Hopefully you see something obvious that I am doing wrong.

2. It seems ldoc doesn’t handle tables like the below.  Do you have any suggestions on how these can be written/formatted to be handled by ldoc?

   — Table full of other tables and stuff myTable = { subTableA = { someStrings = { “this is a string”, – first string “here is another string” – second string } }, subTableB = { someStrings = { “this is a string”, – first string “here is another string” – second string } }, }

Thanks for taking the time to read.   I look forward to hearing back from you.

Best regards,

Tony Godfrey

[DevilSquid_Rene]

Hi Tony,

great to hear that the article moved you to try LDoc. I’m assured this helps on the long run. 

I’m pretty sure I had the same error regarding the CSS files. Just can not remember how I solved it.

Let me check the settings you use. I will get back to you.

René

[DevilSquid_Rene]

I’m wondering: shouldn’t the values in your bash script be in quotes like this?

1. project_base_name=“Hoppy Naut”

[DevilSquid_Rene]

Are you using a customized CSS file?

[DevilSquid_Rene]

I had success with the following LDoc syntax to document tables with subtables:

------------------------------------------- -- A test to document tables with LDoc -- @module TableTest ------------------------------------------- -- The Person table stores information about the persons. -- -- @table Person -- @field name The name of the person -- @field age The age of the person -- local Person = { name = "John Doe", age = 40, ------------------------------------------- -- The Hobbies of that Person -- -- @table Person.hobbies -- @field name The name of the hobby -- @field spent How much the person has spent on that hobby -- hobbies = { { name = "Painting", spent = 175 }, { name = "Cycling", spent = 2034 }, } }

When I take away the @module options from the first lines, I get some errors. So make sure the files does have a @module.

I don’t know if this matches your table structure, but maybe you can adopt to yours?

[tonygod]

Thanks for all the tips, DevilSquid.  It took me a while to get back around to play with the table again, but your suggestion to use @table and @field works just fine.

I still haven’t managed to figure out what is wrong with the bash script, but I have a workaround that is working okay for me now.

Best regards,

Tony

[hector7]

hi Rene, I liked a lot LDoc from what I saw in the CoronaGeek show, and I tried to install it but I’m getting this error:

I already installed Brew, luarocks and PenLight. I also put the two sublime config files in ~/Library/Application Support/Sublime Text 3/Packages/User/LDoc

I wonder what I could be doing wrong

lua: /usr/local/share/lua/5.2/pl/dir.lua:339: attempt to index local 'p' (a nil value) stack traceback: /usr/local/share/lua/5.2/pl/dir.lua:339: in function '\_makepath' /usr/local/share/lua/5.2/pl/dir.lua:344: in function \</usr/local/share/lua/5.2/pl/dir.lua:337\> (...tail calls...) /Users/hectorgabrielsanchezperez/LDoc/ldoc/tools.lua:227: in function 'check\_directory' /Users/hectorgabrielsanchezperez/LDoc/ldoc/html.lua:324: in function 'generate\_output' /Users/hectorgabrielsanchezperez/LDoc/ldoc.lua:830: in main chunk [C]: in ? [Finished in 0.0s with exit code 1] [shell\_cmd: lua ~/LDoc/ldoc.lua '' -p '' -d '/doc'] [dir: /Users/hectorgabrielsanchezperez/Desktop/test] [path: /usr/bin:/bin:/usr/sbin:/sbin]

[hector7]

I was able to make LDoc work from Terminal, so most likely the problem is in the Sublime Text setup, let me keep digging into this

[DevilSquid_Rene]

Hi Hector,

did you manage to make it run from Sublime?

Otherwise you can post your Sublime settings code here, I can check if the code runs in my set up.

Best

René