Keywords/language reference pages

[gillenhaalb]

On hold until migration to Q# language repo is settled (links will all direct to respective pages there).

Addresses the broader discussion in #939. Creates separate pages for each Q# keyword (for searchability). Also some language constructs/symbols.

Content for pages:

• brief description
• links to
  1. User Guide section where it's discussed
  2. and/or new internal pages from qsharp-language repo (stubs created at PR create stub files for qsharp-language topics #1075 )
• code examples of use (preferably from samples?)

To-do:

• group main page contextually? Align with TOC folders, can lend more info than simple alphabetical order (not to mention everyone will likely ctrl+f to find anything they're looking for anyway)
• expand EntryPoint and Test API pages because linking to them directly (i.e. add the content that will be on other pages: more explanation, links, examples)

Additional pages to be added:

• ! unwrap operator
• < > type parameterized callables
• w/ <- copy-and-update expressions (array elts and named items
• w/= <- update-and-reassign statements (used with set for named items and array items)
• ? | conditional expression
• (maybe) new page for each operator? (list here)

[cgranade]

This and @Test are both attributes that are already documented in the API reference; can we link to those from the TOC rather than duplicating that content?

[gillenhaalb]

@cgranade That's a great point, thanks. Just to clarify, it sounds like you mean keeping the links in the TOC dropdown (and the keyword list page), but simply linking direct to the API page?

[cgranade]

I think that should work, yeah. If I recall, you can make href properties in toc.yml point to xrefs instead of Markdown file paths; that would allow for reusing the automatically generated references for Test and EntryPoint.

[opbld32]

Docs Build status updates of commit 96222ea:

⚠️ Validation status: warnings

File	Status	Preview URL	Details
articles/user-guide/language-ref/toc.yml	⚠️Warning		Details
articles/user-guide/language-ref/attributes/entrypoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/attributes/test-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/let-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/mutable-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/new-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/set-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/adjoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/controlled-adjoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/controlled-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/auto-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/distribute-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/intrinsic-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/invert-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/self-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/adjoint-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/body-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/controlled-adjoint-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/controlled-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/partial-app-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/return-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/adj-ctl-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/adj-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/ctl-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/fn-signature-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/op-signature-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/apply-within-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/elif-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/else-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/fail-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/fixup-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/for-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/if-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/in-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/repeat-until-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/while-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/function-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/internal-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/newtype-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/operation-ref.md	✅Succeeded	View
articles/user-guide/language-ref/language-reference.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/as-ref.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/namespace-ref.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/open-ref.md	✅Succeeded	View
articles/user-guide/language-ref/qubits/borrowing-ref.md	✅Succeeded	View
articles/user-guide/language-ref/qubits/using-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/bigint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/bool-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/double-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/false-ref.md	✅Succeeded	View

This comment lists only the first 50 files in the pull request.

articles/user-guide/language-ref/toc.yml

• Line 154, Column 13: [Warning-file-not-found] Invalid file link: 'microsoft.quantum.core.entrypoint'.
• Line 156, Column 13: [Warning-file-not-found] Invalid file link: 'microsoft.quantum.diagnostics.test'.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching in the Docs contributor and Admin Guide
• See the frequently asked questions
• Post your question in the Docs support channel

[opbld30]

Docs Build status updates of commit a516dd2:

❌ Validation status: errors

Please follow instructions here which may help to resolve issue.

File	Status	Preview URL	Details
articles/user-guide/language-ref/toc.yml	❌Error		Details

articles/user-guide/language-ref/toc.yml

• Line 154, Column 13: [Error-yaml-syntax-error] While scanning for the next token, found character that cannot start any token.

For more details, please refer to the build report.

If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please:

• Try searching in the Docs contributor and Admin Guide
• See the frequently asked questions
• Post your question in the Docs support channel

[opbld31]

Docs Build status updates of commit 4a0e1bf:

✅ Validation status: passed

File	Status	Preview URL	Details
articles/user-guide/language-ref/attributes/entrypoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/attributes/test-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/let-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/mutable-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/new-ref.md	✅Succeeded	View
articles/user-guide/language-ref/binding-assignment/set-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/adjoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/controlled-adjoint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/functors/controlled-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/auto-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/distribute-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/intrinsic-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/invert-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/directives/self-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/adjoint-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/body-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/controlled-adjoint-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/op-specializations/tags/controlled-tag-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/partial-app-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/return-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/adj-ctl-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/adj-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/ctl-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/fn-signature-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/callables/signature/op-signature-symb-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/apply-within-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/elif-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/else-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/fail-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/fixup-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/for-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/if-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/in-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/repeat-until-ref.md	✅Succeeded	View
articles/user-guide/language-ref/control-flow/while-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/function-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/internal-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/newtype-ref.md	✅Succeeded	View
articles/user-guide/language-ref/declaration/operation-ref.md	✅Succeeded	View
articles/user-guide/language-ref/language-reference.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/as-ref.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/namespace-ref.md	✅Succeeded	View
articles/user-guide/language-ref/namespace/open-ref.md	✅Succeeded	View
articles/user-guide/language-ref/qubits/borrowing-ref.md	✅Succeeded	View
articles/user-guide/language-ref/qubits/using-ref.md	✅Succeeded	View
articles/user-guide/language-ref/toc.yml	✅Succeeded
articles/user-guide/language-ref/types/bigint-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/bool-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/double-ref.md	✅Succeeded	View
articles/user-guide/language-ref/types/false-ref.md	✅Succeeded	View

This comment lists only the first 50 files in the pull request.
For more details, please refer to the build report.

Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.

For any questions, please:

• Try searching in the Docs contributor and Admin Guide
• See the frequently asked questions
• Post your question in the Docs support channel

[geduardo]

@gillenhaalb is this PR outdated/closeable?

[gillenhaalb]

@gillenhaalb is this PR outdated/closeable?

@geduardo Its motivation is definitely still there and it will be my priority after Learn, but I would file it under "perhaps" closeable. The reason being that there wasn't too much work done on the pages themselves, but the skeleton that's setup currently is still essentially what we'll use. The only outdated part is the links to the language ref pages will be updated to xrefs now that we're hosting them in the same docset.

Since setting up the skeleton was somewhat laborious, we wouldn't want to have to re-do all of it. However, there is still a hefty amount to be done on the pages (descriptions, code examples, etc.; which will probably get a few others involved) and it shouldn't stand in the way of migration, so I'd say it would certainly be closeable provided we don't delete the branch. Should I go ahead and close?