IMP Doc

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.

• Basic
• DHP's Implementation
  • Annotations
  • IMP-Doc for Commands
• Further Reading
• References
• History

Basic

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.

DHP's Implementation

You can use MarkDown syntax in descriptions within IMP-Doc.

Annotations

Most of the annotations in IMP-Doc haven't gotten a special meaning in DHP yet. We will provide support for them gradually.

Exceptions are @api, @public, and @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 some examples:

#>
# 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

Further Reading

See Access Modifiers to learn about how to use access modifier annotations to limit the visual scope of resources.

References

• IMP Documentation Format (IMP-Doc)

History

Version	Description
3.0.0	First introduced.