Feedback on documentation (questions, typos, suggestions, etc.)

[alekdavis]

Here some suggestion that can improve the documentation:

1. Installation: If I am not dreaming, there used to be a link pointing to a page with all installation elements, but I can't find it anymore and it is not available in the menu. It would be useful for sharing (I would send a single link to team members who need to install the tool instead of multiple links). Notebook and Docker installation should be marked as optional (I first assumed they were required).
2. Definitions: What is a region? It is mentioned in several sections but there is no description. Is it just a request-specific section? Can a region have multiple requests? Can a single request have multiple regions?
3. Title (https://httpyac.github.io/guide/metaData.html#title): I re-read it multiple times and I'm still unclear what it means. Is it only needed for CLI? How is the first example # @title get json functionally different from the second example ### get json? So, if we use # @title, we do not need ###` to separate regions/requests?
4. Loop (https://httpyac.github.io/guide/metaData.html#loop): Is there a way to exit a loop before it finishes normally (e.g. from a pre-/post-request script after checking some condition)? Are pre-request/post-request scripts executed once per test run or once per loop iteration?
5. For loop (https://httpyac.github.io/guide/metaData.html#for): What is the initial index (I know it's zero, but it's not mentioned)? Can a loop start from 1, 2, or whatever? Can index be formatted (say, for the loop 1-999, I need to convert it to a 3-digit value, like 001, 002, etc.)? The code example does not work (need to add the region separator ### at the top, I suspect it should apply to other loop examples).
6. Sleep (https://httpyac.github.io/guide/metaData.html#sleep): Can a variable be used to define the sleep time? Can sleep be combined with a loop? Use case: I create an item, but it may take a few seconds or more to complete provisioning, so the GET operations after POST may fail; it would be nice to be able to make a few GET tries with a sleep in between until the last one fails or a successful GET is made.
7. Global scripts (https://httpyac.github.io/guide/scripting.html#global-scripts): Are they executed once per region/request or once per test run?
8. Asserts (https://httpyac.github.io/guide/assert.html): The endsWith assertion has a wrong example. Can simple asserts use logical AND, OR operations (e.g. check for three status codes)? How to test for match (or non-match) of leading/trailing spaces?
9. Simple ?? asserts (https://httpyac.github.io/guide/assert.html#assert-syntax): What is the ?? notation? Is it described anywhere (outside of httpYac) in more detail? Or is it httpYac specific? How do you check if the response body (and not a property of the body) is an array? Is there a isJson/isDate/isTime/isDateTime/isGuid function or is it limited to what is illustrated in the documentation? How do you check for empty/non-empty string? How do you check for not, e.g. !startsWith? Can you make a case-insensitive string comparison?
10. JavaScript asserts (https://httpyac.github.io/guide/assert.html#javascript-assert): Are these described in more details anywhere outside of httpYac? Or is it httpYac specific? It would be nice to have more extensive docs on asserts or a link to more info if it is available elsewhere.
11. It would make sense to create a section dedicated to authorization topic (it is hard to find).
12. A section on logging/output would be helpful (i.e. there are three httpYac output options, so what is the difference between them).
13. It would be helpful to have an overview of the codelens options. E.g. what is the difference between using Send and Send Repeat? How are requests submitted via codelens different from the test run via the Testing view?
14. Variables (https://httpyac.github.io/guide/variables.html#variable-scope): The section should mention that the variable values may persist between the request runs, unless the environment is reset. It may not be obvious.
15. Request body (https://httpyac.github.io/guide/request.html#request-body): It would be nice if the example included multiple form input variables (do you put them on separate lines? separate by ampersands like a query string?).
16. Variables (https://httpyac.github.io/guide/variables.html#variables): How do you define non-primitive variables, such as arrays, etc? I understand that they can be defined using the JavaScript syntax inside of the {{}} block, but can they be defined using the @ annotation?
17. Global scripts (https://httpyac.github.io/guide/scripting.html#global-scripts): What is the scope of the global script execution? Will they be executed always for every request in the same file only? Or for any request during the test run? Is there a way to make a global script run only once per test run (so it is not tied to a particular request, but as long as it runs once, we're good)? Is there a way to define global scripts for a specific folder (at any level of the folder structure)? If so, can they be marked to run once per test run?
18. Default headers (https://httpyac.github.io/guide/request.html#headers): What is the ellipses (... in ...defaultHeaders) notation in the example?
19. Requests (https://httpyac.github.io/guide/request.html#headers): What does the {{+ notation mean? What's the purpose of the plus sign?
20. Environments (https://httpyac.github.io/guide/environments.html#json): Can $shared and $default be used with the IntelliJ environment files? How would you use private environment files with JSON environments? Can httpYac support .user environment files (like https://learn.microsoft.com/en-us/aspnet/core/test/http-files?view=aspnetcore-8.0#user-specific-environment-files)?
21. Canceling requests: If there is a way to cancel a running requests (similar to https://github.com/Huachao/vscode-restclient/tree/master?tab=readme-ov-file#cancel-request), it would be nice to know how.
22. Require (https://httpyac.github.io/guide/scripting.html#require): The tip text (External dependencies must be installed independently, exceptions are , , and Dependency, which are provided from the extension) is confusing. It would be nice to have more detailed instructions explaining how to use external dependencies.
23. Extended asserts (https://httpyac.github.io/guide/assert.html#extended-asserts). The chai example does not work (probably due to chai require from .http not supported AnWeber/vscode-httpyac#268. Instructions on how to use a more comprehensive assertion library (chai or whatever) would be very helpful.