IMP-Doc is a special type of comment that can increase the readability of your mcfunctions and make it easier for you to write data packs.
The IMP-Doc support provided by DHP is based on the Interoperable Module Protocol Documentation Format proposed by Arcensoth, please take a look at the specification first. We will then cover the things that you should know when using IMP-Doc in DHP.
You can use MarkDown syntax in descriptions within IMP-Doc.
Most of the annotations in IMP-Doc haven’t gotten a special meaning in DHP yet. We will provide support for them gradually.
@within. They are used to change the visibility of resources in DHP; see
Access Modifiers for more information.
Certain annotations proposed by IMP-Doc require some parameters, e.g. the
@input score <name> <objective> [description] annotation that can lists all the score inputs of the function.
In DHP’s implementation, you can break at any spaces that separate different parameters of an annotation and
turn into a new line with indentation (>= 2 spaces). For example, all the following comments are legal and
have the same meaning in DHP:
#> example:foo # @input score $bar mypack.baz Description for the first score. # @input score $bar mypack.qux Description for the second score. #> example:foo # @input # score $bar mypack.baz Description for the first score. # score $bar mypack.qux Description for the second score. #> example:foo # @input # score $bar mypack.baz # Description for the first score. # score $bar mypack.qux # Description for the second score. #> example:foo # @input score $bar # mypack.baz # Description for the first score. # mypack.qux # Description for the second score. #> example:foo # @input # score # $bar # mypack.baz # Description for the first score. # mypack.qux # Description for the second score.
IMP-Doc for Commands
Apart from writing IMP-Doc in the first line of a mcfunction to describe the whole file, you can also write
IMP-Doc in front of certain commands to describe the resources defined/declared by them. The key difference
is that you do not write the function ID after the
#> characters in the first line of the comment. Here are
#> # A bossbar that is for xxx. # - Max: 100. # - Value: should be the amount of xxx. # @internal bossbar add spgoding:foo "" #> This tag is used by xxx. #declare tag qux
For a complete list of commands/comments that can define/declare resources, see Declare Comment.
You can add an indentation (>= 2 spaces) before the commands after the IMP-Doc to make a single doc comment affect multiple definitions/declarations at the same time. e.g.
#> A set of teams with colors. team add example.red team add example.blue #> # Score holders for xxx calculation. # @within spgoding:calc/** #declare score_holder a #declare score_holder b #declare score_holder c
See Access Modifiers to learn about how to use access modifier annotations to limit the visual scope of resources.