QSharpTripleSlash

Joe Clapis

|
175 installs
| (1) | Free
QSharpTripleSlash provides automatic creation and Intellisense autocompletion of documentation comments (triple-slash comments) for operations, functions, and newtypes in Q# code. It brings the convenience of Visual Studio's automation support for C# XML-style documentation co...

QSharpTripleSlash

QSharpTripleSlash is a Visual Studio extension that autogenerates documentation comments for Q# code. It was inspired by cpptripleslash, which brought C#-style documentation completion and Intellisense support in Visual Studio to C++. This extension is a spiritual successor meant for Q# developers.

Features

Q# code is documented with comment blocks that start with three forward-slashes.

This can be tedious to write out by hand, especially for operations and functions that have a large number of parameters. QSharpTripleSlash does this for you, by automatically creating the comment skeleton for you as soon as you type three forward-slashes above an operation, function, or newtype definition:

It will automatically add an # Input section if your method has input parameters, and a subsection for each one. It will also add an # Output section if your method returns something besides UnitType. It also supports Type Parameters.

Pressing Enter on a line within a documentation comment will automatically add a new line that has three forward slashes and is properly indented, making it easy to write multiline comments.

Finally, QSharpTripleSlash comes with simple support for Markdown section autocomplete suggestions:

alt text

These section suggestions (and their tooltip descriptions) are all derived from Q#'s official documentation.

Prerequisites

Configuration

Some of the extension's behavior is determined by an included TOML configuration file. This currently includes:

  • Logging level
  • Number of lines in-between Markdown sections
  • Number of lines in-between parameter subsections

The config file contains documentation that explains each of the modifiable settings and their options. More may be added based on demand.

License

Copyright (C) 2019 The MITRE Corporation.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This project contains content developed by The MITRE Corporation. If this code is used in a deployment or embedded within another project, it is requested that you send an email to opensource@mitre.org in order to let us know where this software is being used.