wip: docs overhaul

docs/api/01-docblocks.mdx

@@ -0,0 +1,274 @@
+---
+sidebar_position: 2
+---
+
+# Docblocks
+
+:::info
+
+Docblocks cannot be applied to `describe` statements.
+If you want to apply a docblock to all tests in the file,
+you can put it on the first line of the file.
+
+:::
+
+Docblocks are a powerful way to add metadata to your tests using JSDoc-style comments. These annotations are parsed by `jest-allure2-reporter` to enhance your test reports with additional information.
+
+## Plain comments
+
+Plain comments act as [`@description`](#description--desc) annotations, when applied to a test case.
+
+```javascript
+/**
+ * This test demonstrates the addition operation.
+ */
+test('should add two numbers', () => {
+  expect(1 + 2).toBe(3);
+});
+```
+
+For hooks, they act as [`@displayName`](#displayname) annotations.
+
+```javascript
+/**
+ * Navigate to the home page
+ */
+beforeEach(async () => {
+  await page.goto('https://example.com');
+});
+````
+
+## `@description` / `@desc`
+
+Adds a Markdown description to a test case.
+
+```javascript
+/**
+ * @description
+ * This test demonstrates the addition operation.
+ */
+test('should add two numbers', () => {
+  expect(1 + 2).toBe(3);
+});
+```
+
+## `@descriptionHtml`
+
+Adds an HTML description to a test case.
+
+```javascript
+/**
+ * @descriptionHtml
+ * This test demonstrates the <code>-</code> operator.
+ */
+test('should subtract two numbers', () => {
+  expect(2 - 1).toBe(1);
+});
+```
+
+## `@displayName`
+
+Overrides test names specified in `test('...')` or `it('...')` in the test report.
+
+```javascript
+/**
+ * @displayName 1 + 1 = 2
+ */
+test('First test', () => {
+  expect(1 + 1).toBe(2);
+});
+```
+
+When applied to a hook, it sets a custom display name for the hook, similar to a [plain comment](#plain-comments):
+
+```javascript
+/**
+ * @displayName Custom "beforeEach" hook
+ */
+beforeEach(() => {
+  // Hook implementation
+});
+```
+
+## `@fullName`
+
+Sets a full name for a test case, which can be used for more detailed identification.
+By default, full names are also used for tracking test history across multiple runs or retries.
+
+```javascript
+/**
+ * @fullName Arithmetic > Addition > Valid assertion
+ */
+test('First test', () => {
+  expect(1 + 1).toBe(2);
+});
+```
+
+## `@historyId`
+
+Assigns a custom history ID to a test case, useful for tracking test history across multiple runs or retries.
+
+```javascript
+/**
+ * @historyId HISTORY-2
+ */
+test('First test', () => {
+  expect(2 + 2).toBe(3);
+});
+```
+
+## `@issue`
+
+Links an issue to a test case.
+
+```javascript
+/**
+ * @issue XMLRPC-15
+ */
+test('Proving the fix', () => {
+  expect(1 + 1).toBe(2);
+});
+```
+
+## `@owner`
+
+Specifies the owner of a test or suite.
+
+```javascript
+/**
+ * @owner John Doe
+ */
+describe('Suite maintained by John', () => {
+  test('First test', () => {
+    // Test implementation
+  });
+});
+```
+
+## `@package`
+
+Specifies the package for a test or suite, useful for organizing tests.
+
+```javascript
+/**
+ * @package e2e.pragmas
+ */
+describe('My service', () => {
+  /**
+   * @testMethod Alternative title for the test
+   */
+  test('should log a message', () => {
+    // Test implementation
+  });
+});
+```
+
+## `@severity`
+
+Sets the severity level for a test or suite.
+
+```javascript
+/**
+ * @severity critical
+ */
+describe('Test suite', () => {
+  test('Important test 1', () => {
+    expect(1 + 1).toBe(2);
+  });
+});
+```
+
+## `@epic`, `@feature`, `@story`
+
+Categorizes tests into epics and features for better organization.
+
+```javascript
+/**
+ * @epic Arithmetic operations
+ * @feature Addition
+ * @story Sane assumptions
+ */
+describe('Test suite', () => {
+  // Test cases
+});
+```
+
+## `@tag`
+
+Adds tags to a test or suite.
+
+```javascript
+/**
+ * @tag docblock, arithmetic
+ */
+describe('Test suite', () => {
+  /**
+   * @tag addition
+   */
+  test('First test', () => {
+    expect(1 + 1).toBe(2);
+  });
+});
+```
+
+## `@thread`
+
+Specifies a custom thread for concurrent tests.
+Do not use it unless you want to control tests on the [Timeline](#TODO) manually.
+
+```javascript
+/**
+ * @thread IV
+ */
+test('First test', () => {
+  expect(1 + 1).toBe(2);
+});
+```
+
+## `@tms`
+
+Links a test management system (TMS) case to a test.
+
+```javascript
+/**
+ * @tms TMS-1234
+ */
+test('should be linked to a TMS ticket', () => {
+  expect(1 + 1).toBe(2);
+});
+```
+
+## `@url`
+
+Adds a custom URL link to a test or suite.
+
+```javascript
+/**
+ * @url https://en.wikipedia.org/wiki/Arithmetic 🔢 Arithmetic
+ */
+describe('Arithmetics', () => {
+  /**
+   * @url https://en.wikipedia.org/wiki/Addition ➕ Addition
+   */
+  test('1 + 1 = 2', () => {
+    expect(1 + 1).toBe(2);
+  });
+});
+```
+
+## `@parentSuite`, `@suite`, `@subSuite`
+
+Organizes tests into a hierarchical suite structure.
+
+```javascript
+/**
+ * @parentSuite Custom Parent Suite
+ * @suite Custom Suite
+ * @subSuite Custom Sub-Suite
+ */
+test('Test outside of any suite', () => {
+  // Test implementation
+});
+```
+
+These docblock annotations provide a powerful way to enrich your tests with metadata, improving the organization and readability of your Allure reports. By using these annotations, you can create more informative and structured test reports that help in better understanding and maintaining your test suite.