LÖVE-API Documentation (as a lua table)

[rmcode]

New update:

Code: Select all

#0.9.2d
### Additions
- Added Thread:isRunning
- Added Thread:start variant
- Added love.graphics.newMesh variant
- Added love.graphics.push variant
- Added StackType

### Fixes
- Fixed Channel:push
- Fixed Channel:supply

### Other Changes
- Updated love.graphics.push
- Updated love.graphics.newThread
- Updated MeshDrawMode
- Updated CanvasFormat

I'd also love to get some input on this.

[leafi]

rmcode, cheers for maintaining this. I've been using it to produce LuaDoc for the new Eclipse LDT and it's working out pretty well.

There's a couple of types that are referenced in the table but not defined anywhere, and aren't Lua primitive types. I'll try to chuck in a couple of pull requests for ones that are due to wiki stuff just not being present yet.

(For reference/in case I don't:

• "light userdata": OK, this is a Lua type of sorts, but I'm not sure what to convert it to.
• "value" (physics.Body:getUserData()): Encoding this as untyped for now.
• "mixed": Guess this literally is untyped
• "any": Same as mixed...?
• "SearchOrder" (2nd arg to love.filesystem.setIdentity): Wiki says this should be a boolean now?
• "ShaderVariableType": No documentation on wiki about this. I'm currently encoding this as untyped.
• "Texture": A fair few functions in Graphics.lua refer to this, but there's no type definition. I'm patching in a simple definition inside my code at the moment, and adding it as a supertype of Canvas and Image.
• "WheelJoint": Despite appearing not to be defined on the wiki, it actually is! Search can find it.
• "MessageBoxType" (love.window): Simple enum that's present on the wiki. Just absent atm.

)

With those changes, all types in the API table that are referenced are either Lua primitive types or are defined in the table.

[rmcode]

Released 0.9.2e:

Code: Select all

### Additions
- Added missing Event Constants (see [PR #5](https://github.com/rm-code/love-api/pull/5)) 	
- Added description fields for variants of love.graphics.push
- Added description fields for variant of love.graphics.newFont

### Structure changes
- The field containing function variants is now called 'variants' instead of 'functions' (see [PR #6](https://github.com/rm-code/love-api/pull/6) and [#2](https://github.com/rm-code/love-api/issues/2))
- Variants now have an (optional) description field

### Fixes
- Moved getDopplerScale and setDopplerScale from Source to love.audio

### Other Changes
- Updated description of love.audio.getDistanceModel

This update introduced a small change to the api structure:

The structure of a function in the api looks like this now:

Code: Select all

-- Functions
functions = {
    { -- Function 1
        name = 'Name of the function',
        description = 'The description of what the function does',
NEW -->variants = { -- Renamed from 'functions'
            {
NEW -->    description = 'The description detailing what this variant does', -- Added optional description field for each variant
                arguments = { -- (optional)
                    {
                        type = 'The variable type',
                        name = 'The variable name',
                        description = 'The description of the variable.'
                    },
                    {
                        -- Argument 2
                        -- ...
                    },
                },
                returns = { -- (optional)
                    {
                        type = 'The returned variable type',
                        name = 'The variable name',
                        description = 'The description of the variable.'
                    },
                    {
                        -- Return statement 2
                        -- ...
                    },
                }
            },
        },
    },
    {
    -- Function 2
    -- ...
    },
}
 

[Positive07]

I have a couple of things that would be nice to add:

- Examples: Examples for functions would be nice, as they

Code: Select all

examples = {
     {
          description = "Draws a filled arc"
          example = [[
               love.graphics.arc('fill',...)
          ]];
     }
     {
          description = "Draws a line arc, note that the remaining rect lines are also drawn"
          example = [[
               love.graphics.arc('line',...)
          ]];
     }
}

- Related: Related pages as they are in the bottom of the wiki pages:

Code: Select all

related = {
     "love.graphics.newImage",
     "Image",
     "CompressedData",
}

- Links: When you talk about other sections of the API it would be nice to detect that with some simple string matching and get the section of the API where that function is located:

Code: Select all

description = "...You can set where love.filesystem will look by setting the identity with love.filesystem.setIdentity or the t.identity field in conf.lua"

Let's think this is part of love.filesystem description, you could put a link where it says love.filesystem.setIdentity and where it says conf.lua

You could detect this if the string was something like:

Code: Select all

description = "...You can set where love.filesystem will look by setting the identity with [love.filesystem.setIdentity] or the t.identity field in [conf.lua]"

Note that the code is still readable and you can easily guess why there are square brackets, then you could do some string.gmatch magin and easily grab those strings:

Code: Select all

for start,word,end in string.gmatch(description, "()%b[]()") do
     --Put a link in that word!
end

Note that for links and related pages you may need a look-up table, since things like "Image" are not easily found, since you dont easily know which module they are in...

What do you say rmcode? Are you interested in any of these ideas?

[rmcode]

First of all: sorry for the late reply.

I think the examples would only be useful for an interactive demo / wiki like zorg suggested. The text links sound like an interesting idea though and they could be useful for docs like in ZeroBraneStudio.

[Positive07]

First of all: sorry for the late reply.

No Problem!

I think the examples would only be useful for an interactive demo / wiki like zorg suggested.

Yeah, that is the use I was thinking of, maybe if it is done with a separate file? so not really required and completely external, could do, but not sure. It also makes the file way bigger too

The text links sound like an interesting idea though and they could be useful for docs like in ZeroBraneStudio.

I'm glad you liked the idea, I would love to see something implemented around this, tell me if you need help (twitter, github issue or irc) I will love to give feedback on it

[rmcode]

Yeah, that is the use I was thinking of, maybe if it is done with a separate file? so not really required and completely external, could do, but not sure. It also makes the file way bigger too

Yeah that's one of the main issues I see with it. A separate file could work.

I'm glad you liked the idea, I would love to see something implemented around this, tell me if you need help (twitter, github issue or irc) I will love to give feedback on it

Can't promise to work on it in the next few days / weeks since I currently have lots of other stuff to work on If you want to give it a try though I'll gladly accept the pull request

[Positive07]

Can't promise to work on it in the next few days / weeks since I currently have lots of other stuff to work on If you want to give it a try though I'll gladly accept the pull request

If we can discus an interface I have not problem doing it. I would like to know how would the links look in the text, and where should the links be stored, if stored at all, otherwise how to know where to point etc. Also I guess there should be something like a function? dont know.

EDIT: Lets keep this in the issue

[deathbeam]

Is it possible to generate HTML documentation in some simple way from this?

[Positive07]

Is it possible to generate HTML documentation in some simple way from this?

Write a lua script! That is basically the idea of this, is the base to generate other types of documentations, with just a lua script. So yeah it shouldnt be that hard, and you can tweak it to your needs so it's neat!