docs(parseAlgoliaHitReverseSnippet): rewrite guides (#481)

* docs(parseAlgoliaHitReverseSnippet): rewrite guides

* docs(parseAlgoliaHitReverseSnippet): add descriptions

* docs(parseAlgoliaHitReverseSnippet): fix text

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

* docs(reverseSnippetHit): fix example

Co-authored-by: François Chalifour <[email protected]>

Author: sarahdayan

packages/website/docs/parseAlgoliaHitReverseSnippet.md

@@ -2,16 +2,44 @@
 id: parseAlgoliaHitReverseSnippet
 ---
 
+import PresetAlgoliaNote from './partials/preset-algolia/note.md'
+
 Returns the non-matching parts of an Algolia hit snippet.
 
-This is a common pattern for Query Suggestions.
+The `parseAlgoliaHitReverseSnippet` function lets you parse the non-highlighted parts of an Algolia hit's snippet. This is a common pattern for [Query Suggestions](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/), where you want to highlight the differences between each suggestion.
+
+<PresetAlgoliaNote />
+
+## Installation
+
+First, you need to install the preset.
+
+```bash
+yarn add @algolia/autocomplete-preset-algolia@alpha
+# or
+npm install @algolia/autocomplete-preset-algolia@alpha
+```
+
+Then import it in your project:
+
+```js
+import { parseAlgoliaHitReverseSnippet } from '@algolia/autocomplete-preset-algolia';
+```
+
+If you don't use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-preset-algolia@alpha"></script>
+```
 
-## Example with a single string
+## Examples
+
+### With a single string
 
 ```js
 import { parseAlgoliaHitReverseSnippet } from '@algolia/autocomplete-preset-algolia';
 
-// Fetch an Algolia hit
+// An Algolia hit for query "lap"
 const hit = {
   name: 'Laptop',
   _snippetResult: {
@@ -20,20 +48,20 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitReverseSnippet({
+const reverseSnippetedParts = parseAlgoliaHitReverseSnippet({
   hit,
   attribute: 'name',
 });
 
-// => [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
+// [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
 ```
 
 ## Example with nested attributes
 
 ```js
 import { parseAlgoliaHitReverseSnippet } from '@algolia/autocomplete-preset-algolia';
 
-// Fetch an Algolia hit
+// An Algolia hit for query "lap"
 const hit = {
   name: {
     type: 'Laptop',
@@ -46,24 +74,30 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitReverseSnippet({
+const reverseSnippetedParts = parseAlgoliaHitReverseSnippet({
   hit,
   attribute: ['name', 'type'],
 });
 
-// => [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
+// [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
 ```
 
-## Params
+## Parameters
 
 ### `hit`
 
 > `AlgoliaHit` | required
 
-The Algolia hit to retrieve the attribute value from.
+The Algolia hit whose attribute to retrieve the reverse snippet from.
 
 ### `attribute`
 
 > `string | string[]` | required
 
-The attribute to retrieve the reverse snippet value from. You can use the array syntax to reference the nested attributes.
+The attribute to retrieve the reverse snippet from. You can use the array syntax to reference nested attributes.
+
+## Returns
+
+> `ParsedAttribute[]`
+
+An array of the parsed attribute's parts.

packages/website/docs/reverseSnippetHit.md

@@ -2,36 +2,84 @@
 id: reverseSnippetHit
 ---
 
-Returns a virtual node with non-matching parts of an Algolia hit snippet.
+Returns virtual nodes with highlighted non-matching matching parts of an Algolia hit's snippet.
 
-## Example
+The `reverseSnippetHit` function lets you turn an Algolia hit's snippet into a virtual node with highlighted non-matching parts for a given attribute.
+
+## Examples
+
+### With a single string
+
+To determine what attribute to parse, you can pass it as a string.
 
 ```js
 import { reverseSnippetHit } from '@algolia/autocomplete-js';
 
-const hit = {}; // fetch an Algolia hit
+// An Algolia hit for query "zelda"
+const hit = {
+  query: 'zelda switch',
+  _snippetResult: {
+    query: {
+      value:
+        '__aa-highlight__zelda__/aa-highlight__ switch',
+    },
+  },
+};
 const reverseSnippetedValue = reverseSnippetHit({
   hit,
   attribute: 'query',
 });
 ```
 
-## Params
+### With nested attributes
+
+If you're referencing a nested attribute, you can use the array syntax.
+
+```js
+import { reverseSnippetHit } from '@algolia/autocomplete-js';
+
+// An Algolia hit for query "hello"
+const hit = {
+  hierarchicalCategories: {
+    lvl1: 'Video games',
+  },
+  _snippetResult: {
+    hierarchicalCategories: {
+      lvl1: {
+        value:
+          '__aa-highlight__Video__/aa-highlight__ games',
+      },
+    },
+  },
+};
+const reverseSnippetedValue = reverseSnippetHit({
+  hit,
+  attribute: ['hierarchicalCategories', 'lvl1'],
+});
+```
+
+## Parameters
 
 ### `hit`
 
 > `AlgoliaHit` | required
 
-The Algolia hit to retrieve the attribute value from.
+The Algolia hit whose attribute to retrieve the reverse snippet parts from.
 
 ### `attribute`
 
-> `string` | required
+> `string | string[]` | required
 
-The attribute to retrieve the snippet value from.
+The attribute to retrieve the reverse snippet from. You can use the array syntax to reference nested attributes.
 
 ### `tagName`
 
 > `string` | defaults to `mark`
 
 The tag name of the virtual node.
+
+## Returns
+
+> `HighlightItemParams<THit>`
+
+Virtual nodes with the snippet.