🚧 Under Heavy Construction 🚧

This project is undergoing a complete rewrite. We're almost there.

For the legacy VS Code extension known as Data-pack Helper Plus, check out

Branch release/3.3.0 for server-side code;
SpyglassMC/vscode-extension for client-side code;
VS Code Marketplace for use.

Spyglass

Spyglass aims at improving users' editing experience of Minecraft data packs by providing IntelliSense features like real-time error reporting, auto-completion, semantic coloring, code navigation tools, and refactor utilities.

Sample image is from the legacy version of the project

Documentation

WIP at https://spyglassmc.com.

Contributing

 $ git clone https://github.com/SpyglassMC/Spyglass.git

Install Node.js LTS.
```
 $ npm i && npm run build
```

If you're using VS Code to develop Spyglass:

Install the recommended ESLint extension. Make a copy of .vscode/settings.template.json and rename it to .vscode/settings.json. Now your VS Code should automatically fix all linting errors every time you save the file.
Press F5 to run the VS Code extension in development environment. VS Code will automatically compile all packages and build the extension file in watch mode.

Or if you prefer the command line interface:

npm run build to build all packages.
npm run watch to watch changes and build all packages.
npm run clean to remove all js output. Use this when there seem to be caching issues with TypeScript's compiler.
npm test to test all packages.
npm run lint to check linting errors.
npm run lint:fix to fix all auto-fixable linting errors.
npm run commit to run the [gitmoji CLI][gitmoji]. You actually don't have to worry about commit message as long as you're creating PR, as I can always change it.

Please refrain from using mocha --watch, as it might interface with and break the snapshot testing.

Code style

Tabs for indents, spaces for alignment. Except do not align things because the available tooling is unfortunately terrible.

Test docs locally

Install Jekyll according to its documentation.
Run npm run docs:start to start a local preview at localhost:4000.

Build Pipeline

The build script at the root level does the following steps in series:

Run the build script in ./packages/locales.
Run the TypeScript compiler across all packages.
Then, do the two steps in parallel:
1. Run the build script in ./packages/playground.
2. Run the build script in ./packages/vscode-extension.

Credits

The original Spyglass logo was provided by BlackNight0315. The current logo is provided by asd988.

Doc comment specification

Please refer to https://github.com/SPGoding/datapack-language-server/wiki/IMP-Doc.

THE FOLLOWING CONTENT IS OUTDATED

Doc comments are a way to describe a function or a user-defined value for both human and DHP.

There are two types of doc comments: the one for function and the one for user-defined stuff.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Function Doc Comments

Function doc comments MUST be put at the very beginning of a function file.

A doc comment MUST begin with #> instead of #. You MAY put several spaces ( ) or tabs (\t) before or after the beginning symbol. You SHOULD put the function's namespaced ID after this symbol. This ID can be used to perform rename operations, show call hierarchy, and many other features provided by DHP.

It's RECOMMENDED to put other comments after this line to describe the function, usage, and any other related stuff of this function, beginning with #. You MAY put several white spaces ( , \t, \r, \n, or \r\n) before or after these symbols too. Any lines that are not beginning with # (e.g. an empty line, a command, etc.) or are define comments (#define <type> <id>) will break the doc comments at that position.

You MAY use annotations which start with @ to help describe your function, showed below.

Here is an example of a function doc comment.

#> minecraft:foo
# This function is used to balabala.
# Balabala.
# Balabala.
# @author SPGoding
# @input score #foo params <description of #foo parameter>
# @input
#     score #bar params
#     <description of #bar parameter>

# But don't break the streak of `#`s. For instance, there is an empty line before this line, so this line will not be considered as part of the doc comment.

Annotations

Here's a full list of annotations that you can use within your function doc comment. All parameters in the annotation should be seperated with at least one white space. ... indicates that this argument will eat all the characters until the end of this doc comment or encounters another annotation.

Type	Syntax	Description
author	`@author <string...>`	The author of this function.
context	`@context <string...>`	The execution context of this function.
deprecated	`@deprecated [<reason...>]`	This function is deprecated. This annotation affects the semantic coloring token modifier for this namespaced ID.
handles	`@handles <namespaced_id> [<namespaced_id>, ...]`	Marks this function as an event handler.
override	`@override`	Indicates that this function overrides a function intentionally. If `noImplicitOverride` is set to `true` in the config (defaults to `false`), unmarked override will trigger a warning.
patch	`@patch`	The same as `@override`.
input	`@input data (block\|entity\|storage) <id> <path> [<description...>]`	Defines an NBT data input of this function. ~~The `<id>` part will be treated as a private declaration automatically, and will be used to provide completions in this function file.~~ (Still WIP. See #319 for access modifier proposal.)
input	`@input score <score_holder> <objective> [<description...>]`	Defines a score input of this function. ~~The `<score_holder>` part will be treated as a private declaration automatically, and will be used to provide completions in this function file.~~ (Still WIP. See #319 for access modifier proposal.)
output	`@output data (block\|entity\|storage) <id> <path> [<description...>]`	Defines an NBT data output of this function. ~~The `<id>` part will be treated as a private declaration automatically, and will be used to provide completions in this function file.~~ (Still WIP. See #319 for access modifier proposal.)
output	`@output score <score_holder> <objective> [<description...>]`	Defines a score output of this function. ~~The `<score_holder>` part will be treated as a private declaration automatically, and will be used to provide completions in this function file.~~ (Still WIP. See #319 for access modifier proposal.)
private	`@private`	WIP. See #319 for access modifier proposal.
within	`@within <namespaced_id> [<namespaced_id>, ...]`	WIP. See #319 for access modifier proposal.
internal	`@internal`	WIP. See #319 for access modifier proposal.
public	`@public`	WIP. See #319 for access modifier proposal.
custom	`@<custom_annotation_name> [<parameters...>]`	Custom annotations.

Other Doc Comments

Doc comments for other user-defined stuff are similar to function doc comment, but with these differences:

You SHOULD NOT write anything other than white spaces after the beginning #> symbol.
Only author, deprecated, private, within, internal, public, and custom annotations work.

The doc comment MUST be write right before the corresponding stuff. Here are several working examples:

#> 
# Balalala.
# @internal
scoreboard objectives add test dummy

#> 
# Alalalab.
# @deprecated
# @within spgoding:
#define entity SPGoding

Reference: Arcensoth's IMP Function Documentation Format.

spyglassmc / spyglass Goto Github PK

spyglass's Introduction

Spyglass

Documentation

Contributing

Code style

Test docs locally

Build Pipeline

Credits

spyglass's People

Contributors

Stargazers

Watchers

Forkers

spyglass's Issues

THE FOLLOWING CONTENT IS OUTDATED

Function Doc Comments

Annotations

Other Doc Comments

Recommend Projects

Recommend Topics

Recommend Org