Dear Slime, Bartbes, Rude, any other devs, and everyone else in the world,
I'd like to propose to you all (not like that
) that you consider using something like love-api
as the official documentation for future versions of LOVE.
It means better docs can be generated, and IDEs can use it for auto-completion, but it would require a bit of work (hopefully not heaps though), and the wiki already exists so I can understand why you wouldn't want to bother with this proposed idea.
- More flexibility in how the documentation is presented. loveref.github.io isn't perfect, but it's an example of what can be generated from the LOVE API Lua table, and I prefer it to the wiki because it's fast to navigate due to not having to load additional pages, I like that the setters and getters are listed together, I think it looks cleaner, I like the font that I stole from LOVE's homepage, etc. I don't know if everyone likes it, but my point is that generating documentation from the the LOVE API table gives us flexibility in how we want to display it, and something better to use than the wiki could be created. It would be great to create some mobile-friendly documentation for example.
- IDE support. The love-api README lists 9 projects using it for code completion for IDEs/text editors.
- Easier for documentation editors. Edits could be made via GitHub's text editor, and approved before they are merged (I'm not sure if needing to approve changes is a pro or a con). There is less "boilerplate" for adding things to the LOVE API table than to the wiki, for example when adding a function to the wiki one needs to make sure the function name is the same in the page name, the synopsis and the other languages section. Also, the LOVE API table is automatically checked to see if new commits follow the spec. Also, a lot of programmers will already have a GitHub account, and won't need to sign up for a LOVE forums account to make edits.
- Better support for languages other than English. I would recommend trying to use the wiki in another language to see what the current experience is like. For example, from the main page I click "Português". Then I click "love.graphics", and the page is back in English again. I click "Português" again, and anything that hasn't been translated is missing from the page, and old functions are still there. With the LOVE API table, you can generate documentation using the English descriptions instead of the descriptions in the other language when they aren't available, or what I experimented with was Google translating untranslated descriptions. Because only the descriptions are changed, it means that changing the function (e.g. changing the function name) doesn't mean that you lose the translations. For the wiki to work well in another language every single page would need to be translated and kept up-to-date and I don't think this is feasible.
- Easier mass editing. I'm not sure how often this kind of thing would occur, but, for example, the color range change from 0-255 to 0-1 could have been (almost) done with a search and replace.
- You can "query" the LOVE's API, like list the functions that return a boolean, or find out the number of functions LOVE has.
- It allows the documentation to have its own issue tracker, which I think would be quite useful.
- There is some stuff that the LOVE API table doesn't currently do but could do fairly easily I think, like support images (images can be uploaded to GitHub), example code and internal and external links (the internal links, like descriptions linking to functions, in loveref.github.io are automatically generated). Some markup would need to be created.
- There also isn't information about which LOVE versions things were added/removed in, which I also don't think would be difficult to add, but I'm not sure if it's absolutely necessary, as long as there is a version of the documentation for each LOVE version. But, it is nice to know what a renamed function for example has been changed to (LOVE's deprecation output helps in this regard).
- The wiki allows for more freeform editing, which the PixelFormat page makes use of. There could be some structure added to the table to make this kind of page possible, or it could just be linked to externally, but I can understand that when adding documentation you probably don't want to be thinking about how it can be added within the structures the table has or what new structures need to be made.
already exists, but unless it's the official thing that the devs update, I don't think it can be trusted as a source of accurate and up-to-date information, which makes it not very useful, and not very motivating to work on.
In other news, love-api
have been updated to 11.2, thanks to scraping the wiki
(thinking that this used to be updated by manually copy and pasting makes me... uncomfortable). The HTML references also have a "dark mode" if your OS/browser supports that (thanks to codyloyd
And thanks Fuzzlix!
And also huge thanks to Slime for not only developing LOVE but for keeping it so well documented!