I think it would be useful to add the version that specific features were added in to the docs. This would let users know what version of CC:T they need for a specific feature. I'm down to add this myself, but I'd just like to know how this should be implemented. Adding the version to the description would work, but it might look a bit better to add a separate "Since" section below the parameters/return values/usage. This would require an update to illuaminate, which I'm not ready to try to mess with :P.

Example of a possible doc entry:

--- Converts the given color to a paint/blit hex character (0-9a-f).
--
-- This is equivalent to converting floor(log_2(color)) to hexadecimal.
--
-- @tparam number color The color to convert.
-- @treturn string The blit hex code of the color.
-- @since 1.94.0

=>

toBlit(color)

Converts the given color to a paint/blit hex character (0-9a-f).

This is equivalent to converting floor(log_2(color)) to hexadecimal.

Parameters

1. color : number The color to convert.

Returns

1. string The blit hex code of the color.

Since

CC: Tweaked 1.94.0

This would not cover individual parameter additions, however. Adding a "(1.xx.0+)" tag to the end of the parameter would probably work fine.

Put together a quick version history for some of the built-in globals. I don't know, I think this looks fine.

I've pushed the functionality for this to illuaminate, and will push a couple of quick definitions that I wrote to test this. However, taking this off the 1.98 milestone, as realistically I'm not going to be able to do this for the whole documentation before I release that.

Agreed that this'd be a good idea. Kinda been loathe to do it, as it's a whole chunk of work again, but definitely would be nice to have.

I think I'd go a step further and document when a feature was added or changed. For instance, in Python one writes:

    .. versionadded:: 3.7

    .. versionchanged:: 3.9
       Updated to use :meth:`loop.shutdown_default_executor`.

which then gets rendered to:

New in version 3.7.

Changed in version 3.9: Updated to use loop.shutdown_default_executor().

Not sure I'm a massive fan of the names - @since and @changed maybe? Both could then be rendered under a "Changes" section.

The alternative option here is to publish versioned docs, and provide a drop down to switch between versions. It's maybe less easy to digest if you want to go "when did X happen", but if you're working on a specific version I think it's just as useful.

Not sure of a good way of doing this yet - I did have a couple of prototypes, but nothing I was happy with.

This would require an update to illuaminate, which I'm not ready to try to mess with :P.

Yeah, that's fair.