Code documenting

[Zarty55]

What tools do you guys use to document code? I'm tired of updating my own text file with my definitions because it's messy and slow. I remember seeing someone in here talk about libraries that create a documentation file by reading the comments on your own code.

I did some research and I found LDoc. But I have no idea how to use or where to start (From my perspective it's not beginner-friendly).

Anyway, how do you guys handle this?

[Fuzzlix]

I tried LDoc too but i did not grasp the philosophy behind. LDoc seems to have problems (or i had problems) with documenting class methods, switching sections and more.

In my last project i used markdown to write the manual but this project was a small one and probably easier to document than your one.

For my current löve project i develop on Win7 using ZBS. ZBS supports a simple subset of markdown syntax. While developing i document all things in the sources. Finally i can copy and paste the doc comments to a markdown source.

I hope this works.

[raidho36]

One of more standard approaches is to write comprehensive comments to functions, variables and constant declarations in header files. Header files don't apply to Lua but you can do that directly in the source file. Sticking to specific format can then be utilized by generating a manual out of it using some tools like Doxygen.

[master both]

You can check out other proyects that uses LDoc to learn about it, like STI, although a lot of people don't like it, and a some of the people here have made their own documentation proyects, like RTFM or Dox (It's really sad that CentauriSoldier leaved this community and tried to delet his threads).

[Zarty55]

I tried LDoc too but i did not grasp the philosophy behind. LDoc seems to have problems (or i had problems) with documenting class methods, switching sections and more.

In my last project i used markdown to write the manual but this project was a small one and probably easier to document than your one.

For my current löve project i develop on Win7 using ZBS. ZBS supports a simple subset of markdown syntax. While developing i document all things in the sources. Finally i can copy and paste the doc comments to a markdown source.

I hope this works.

I didn't know ZBS could do that! Damn that's good. I think just this will improve a lot my current method. I didn't understand the last part of your comment, I've never programmed anything other than Love2D and some basic C. Could you explain a little bit about markdown and how to use it?

Dox seems really good too. But I think it's too much for my project. I will definitely keep it in mind and will try to learn how to use it better in the future.

Thanks guys!

edit: About ZBS: When I have a file and I want to link a file that is not in the same folder. How do I do that?

[Fuzzlix]

I didn't know ZBS could do that! Damn that's good. I think just this will improve a lot my current method. I didn't understand the last part of your comment, I've never programmed anything other than Love2D and some basic C. Could you explain a little bit about markdown and how to use it?
Dox seems really good too. But I think it's too much for my project. I will definitely keep it in mind and will try to learn how to use it better in the future.

The mardown document description langage aims to be a simple and easy to read text formatting language. The version i use, is
multimarkdown. As a example, how it looks like, you may take a look into the doc folder inside this github project.