Introduce the USAGE.md file

Signed-off-by: Jonatan Waern <[email protected]>

Author: JonatanWaern

CHANGELOG.md

@@ -5,6 +5,8 @@
 # Change Log
 
 ## 0.9.13
+- You can now annotate dml source to disable reporting of specific lints for specific files or lines,
+  see [USAGE.md](USAGE.md) for instructions on how to use it
 
 ## 0.9.12
 - Added 'simics\_util\_vect' as a known provisional (with no DLS semantics)

README.md

@@ -9,7 +9,7 @@ editors, and other tools with information about DML device and common code.
 It currently supports basic syntax error reporting, symbol search,
 'goto-definition', 'goto-implementation', 'goto-reference', and 'goto-base'.
 It also has some basic configurable linting support, in the form of warning
-messages.
+messages. For user-targeted instructions, see [USAGE.md](USAGE.md).
 
 Future planned features are extended semantic and type analysis, basic
 refactoring patterns, improved language construct templates, renaming

USAGE.md

@@ -0,0 +1,47 @@
+<!--
+  © 2024 Intel Corporation
+  SPDX-License-Identifier: Apache-2.0 and MIT
+-->
+# Usage Instructions
+This document describes general instructions and advice directed at
+end-users of the DML language server. For advice or details on
+client implementation see [clients.md](clients.md). This document
+_only_ pertains to details that are client-agnostic. For client-specific
+details consult the documentation of the client.
+
+As this file is currently a work in progress, relevant details may be
+missing or incomplete.
+
+## In-Line Linting Configuration
+It may be desireable to control linting on a per-file basis, rather than
+relying on the linting configuration. This can be done with in-line
+linting configuration inside comments.
+
+The general syntax is:
+`// dls-lint: <command>=<target>`
+Note that only one-line comments are allowed, and only if no text is between
+the comment start and 'dls-lint'.
+
+Currently supported commands are:
+* 'allow-file' Will not report the lint rule specified by \<target> for the
+   entire file, regardless of where 'allow-file' is declared
+* 'allow' Will not report the lint rule specified by <target> for the next
+   line without a leading comment, or for the current line if declared
+   outside a leading comment.
+
+Lint warnings will report which rule caused them in their message, which is the
+same identifier used for \<target>.
+
+For example
+```
+// dls-lint: allow-file=long_lines
+method now_we_can_declare_this_method_with_a_really_really_really_really_long name() {
+
+// dls-lint: allow=nsp_unary
+// dls-lint: allow=indent_no_tabs
+	param p = (1 ++ *
+            4); // dls-lint: allow=indent_paren_expr
+}
+```
+Will allow 'long_lines' globally, 'nsp_unary' and 'indent_no_tabs' on the
+`param p = (1 ++ *` line, and 'indent_paren_expr' on the `'4);` line.