The current IMP doc only covers documentation for functions.
There are already some extensions to this, for example by Datapack Helper Plus.
I think it would be good to come up with a standard for this before we get more conflicting standards.
Things I think are worth to be documented:
- Scoreboard objectives
- Scoreboard players
- Storages (as in the namespaced ID of a storage)
- Bossbars
- Tags (as in tags inside an Entity's
Tags:[]
nbt-tag)
- Teams
- All sorts of JSON files
Currently, IMP doc has to be in the first line of a function file. For non-function file declarations that doesn't make sense, of course. There are several ways such definitions could be applied.
Right where you execute a defining command
This would still be a function comment and is basically what dph+ does.
Since for functions the first line has to include the function's name, I think it would make sense for other things to do the same.
To be able to know what is defined, I propose using a prefix to the resource location (which is optional for function definitions for backwards compatibility)
Example
#> scoreboard 91.ns.main
# The main storage of this data pack
# @internal
scoreboard objectives add 91.ns.main
Considerations
While this works well for things that are actually defined with a single command, such as objectives, bossbars and teams, other things datapacks use are not defined in such a way, including tags, scoreboard players, storages or any JSON definition.
In order to mitigate this, the restriction that the IMP doc has to appear right above the definition could be removed in this case
In a separate file
With this idea, definitions could be put into a separate file (with a custom extension such as .imp
or .impdoc
.
A file could hold multiple such definitions. This might be nice for giving a good overview of a specific directory, for example, such a file could be present in a namespace/advancements/...
directory.
Example
> advancement namespace:technical/detect_kill
Detects a player killing another entity and runs the function namespace:detection/player_kill
@within function namespace:detection/player_kill
> advancement namespace:technical/in_water
Detects a player entering a water source block and runs the function namespace:detection/enter_water
@within function namespace:detection/enter_water
Considerations
While this might be nice for some things, like giving an overview of declarations in a datapack, It would also allow to separate different definitions, for example by declaring a tags.impdoc
including all tags. I don't think it should be the only way. Thinking of e.g. java this feels more like an exported form of Javadoc (or impdoc in this case) instead of an in-code documentation
In a non-vanilla JSON tag (for JSON definitions only)
Pretty self-explanatory, just add a custom JSON tag at the beginning of a JSON file
Example
{
"_impDoc": {
"description": "Detects a player killing another entity and runs the function namespace:detection/player_kill"
"within": {
"type": "function",
"value": "namespace:detection/player_kill"
}
},
// ... (advancement definition here)
}
Considerations
I think this works pretty well and should be possible for anything that's defined as JSON, but of course does not work for anything else, so another solution is needed for those cases.
Anything else?
Feel free to add/ discuss other ideas here