Some ideas

[hahawoo]

I've had a few ideas about this project, and I thought I'd put them all in one issue instead of creating heaps of issues, all of which maybe no one else would think are good ideas. :P I'm sorry there's so much text here, feel free to not read it anyone.

Some of these ideas involve diverging from the wiki a bit, and the idea of this project currently is to stick to what is in the wiki, and I respect that so I might make my own "experimental" fork (and move out the code I've been temporarily storing in the "test" folder of the gh-pages branch), but I thought I'd share my ideas here anyway just in case any of them are useful.

Here are the ideas:

• Have a "serializer" for the table, so the table can be changed in Lua code and then resaved into the same file structure. This could be useful for adding/changing fields or table structure. I've kind of already made this here, using LOVE so that creating directories is easy (maybe it's also easy in plain Lua too, I didn't try).
• Have extra commas at the end of tables (i.e. "},"), it might look a bit weird but it could make copy and pasting and removing code in the table easier, and plus I think it makes the serializer code a little bit simpler.
• Maybe it would be cool to have support for images (or maybe not). If there were images, there should also be a way to get the description without images, for text-only uses.
• Also support for example code, maybe? (I actually don't think example code or images are necessarily appropriate for this API reference, because I think it would be more suitable for a different type of documentation; like how the function descriptions in the Lua reference manual don't have many code examples. But, maybe.)
• Putting the "love" module in its own module folder like the other modules may or may not be useful.
• When I first made the table my idea was to put the wiki information in a table in the simplest way possible, but what I should have done also is to provide easy ways of using it. I thought of adding some base code to the README for this purpose (Any interest in adding "skeleton" code to the README? #51), but now I think it would be more useful to post-process the table to make it easier to use so that code isn't necessary (the full table structure I have in mind and post-processing code can be found here):
• • Tables for functions, types, arguments etc. could have a "what" field with what that table is, i.e. 'function', 'type', etc.
• • There could be a list of all the tables with a "what" field, and other lists which contain just the functions, just the types, etc.
• • Each table could have references to its "context", i.e. a method could have references to its type, the module it's in, etc.
• • There could be other fields which would be useful, like a full name for a function (i.e. the name 'draw' and the full name 'love.graphics.draw'), the corresponding getter/setter of a function, and whatever else would be useful. There are things I haven't added yet which may or may not be useful, like a synopsis for variants and unique string IDs for each table.
• This is an extremely minor and silly quibble, but I'm not sure about the repo name and the table name differing only by the hyphen/underscore, because it leads to it being required like 'love-api.love_api', which is so close to the same name twice, I think I tripped up on this one time using two underscores or something and got confused, so I would be inclined to want it to be either the same name twice.

These are the "diverging from the wiki" ideas:

• Removing the "notes" field from KeyConstant enum. The "notes" field isn't used anywhere else, and the information can be merged in to the "description" field.
• Global/object state can have an initial value, which isn't documented in the wiki, for example the initial color state is (255, 255, 255, 255). It might be useful to document this.
• It might also be useful to document ways in the which the function can error or fail without error (i.e. the filesystem functions).
• The wiki has mini description for functions which are used on the module/type pages, which I think could be useful especially for languages other than English where the function name by itself isn't self-explanatory. I wrote some code which grabbed this information from the wiki, but then I realized that it's basically a copy of the first line of the full description. So, perhaps "the first line of the description should work as the mini description" could be a thing.
• Checking the consistency of the documentation. For example, the description of getters often start with both "Returns the" and "Gets the", and names of argument/returns sometimes use camelCase and sometimes use lowercase.
• Removing references in descriptions to previous versions, i.e. 'In version 0.9.2 and older...'. I don't think this is useful information to keep around, because if one is using a previous version they can use a previous release of the LOVE-API table.
• Combining variants which differ only by argument type (see this thread).

[hahawoo]

Experimental fork is here: https://github.com/santoslove/love-api-experiments