improve Doc

Signed-off-by: Matthias Gatto <[email protected]>

HACKING.md

@@ -2,12 +2,11 @@
 
 *Essential Information for Hacking COGNAC*
 
-## Enabling debug
+## Enabling Debug Mode
 
-To enable debug, use `--debug-mode` in `./configure`
+To enable debug mode, use the `--debug-mode` option with the `./configure` command
 
-then the `debug` commande in the shell script will print some information.
-without this option debug will print nothing
+Once enabled, the `debug` command in the shell script will print debug information. Without this option, the debug command will not output any information.
 
 ## Unix Philosophy and COGNAC Paradigms.
 
@@ -42,25 +41,25 @@ A relatively easy way to add a feature in Cognac is to start by modifying the ge
 
 For exemple, if you modify a function like `parse_thatarg()` in "osc_sdk.c", once the changes are working, you can then search (using a tool like grep) through the generator code to find where `parse_thatarg` is generated. From there, you can add modifications to the generator to make the change permanent and automated.
 
-## Example to add a new API, that doesn't work at first.
+## Example: Adding a New API That Initially Doesn't Work.
 
-Let's say you ahve configure cognac like this
+Let's say you have configured Cognac like this:
 
 ```sh
  ./configure --sdk-name=myapi-sdk   --cli-name=guru --api-script='cat myapi-api.json  > osc-api.json' --debug-mode --from-path
 ```
 
-doing that you will use try to generate the api from path, with debug enable.
+By doing that, you will attempt to generate the API from the path with debug enabled.
 
-now let's say you have this output while calling `make`:
+Now, let's say you get this output while running `make`:
 ```
 ____complex_struct_func_parser____
 nothing found____cli_parser____
 nothing founderror in <stdin> jsonnothing founderror in <stdin> jsonnothing founderror in <stdin> jsonnothing founderror in <stdin> jsonnothing founderror in <stdin> jsonnothing founderror in <stdin> jsonnothing founderror in <stdin> json./cognac_gen.sh lib.h osc_sdk.h c
 debug mode is on
 ```
 
-This mean that durring `____complex_struct_func_parser____` `____cli_parser____`, the scripts fails to pasre some part of osc-api json.
+This mean that during `____complex_struct_func_parser____` `____cli_parser____`, the script fails to parse some parts of `osc-api.json`.
 To debug it, you should look at what happen durring `____complex_struct_func_parser____` and `____cli_parser____` inside `cognac_gen.sh`
 
 

README.md

@@ -35,13 +35,13 @@ For example, if the API has a call named `CreatePony`, the corresponding compone
 
 You can modify the suffix of functions by using `--function-suffix=FUNCTION_SUFFIX` option with `./configure` command.
 
-Or you can generate functions using what is inside `paths`, using `./configure --from-path`
+Alternatively, you can generate functions based on the contents of `paths` by using the `./configure --from-path` option.
 
 *Note: There are two versions of yq: one written in Python and one in Go. The default version depends on your distribution. On Arch-based distributions, the Python version is typically the default, whereas on Debian-based distributions, the Go version is default. COGNAC supports both, but to use the Go version, you need to pass `--yq-go` to `./configure`.*
 
 ### Examples: Generating a CLI for a New API
 
-#### Configure cognac for an Api using elements in schema as entry point for API Calls
+#### Configure Cognac for an API using elements in the schema as entry points for API calls.
 
 Let’s say you have an API that is not the Outscale API, and you want to generate a CLI for it.
 You have a URL to a YAML file, such as `https://ponyapi.yolo/`, and the API request components are named `XInput` instead of `XRequest`.
@@ -74,21 +74,21 @@ Here’s what the script does:
 2. Converts the YAML to JSON using yq `$(YQ_ARG)`. *Note the usage of `$(YQ_ARG)`, so ./configure can handle go version of yq*
 
 
-#### Configure cognac for an Api using elements in path as entry point for API Calls
+#### Configure Cognac for an API using elements in the path as entry points for API calls.
 
 For this example we will use [guru](https://apis.guru/api-doc/)
 
-Run the following commande
+Run the following command:
 ```
 ./configure --sdk-name=guru-sdk --cli-name=guru --from-path --api-script='curl -s https://api.apis.guru/v2/openapi.yaml | yq $(YQ_ARG)" > osc-api.json'
 ```
 
-`--cli-name=guru` set the generated binary name to `guru`
-`--sdk-name=guru-sdk` set the generate sdk name and UserAgent to `guru-sdk`
-`--from-path` generate API calls from elements in `paths` instead of `components.schemas`
+`--cli-name=guru`: Sets the generated binary name to `guru`.
+`--sdk-name=guru-sdk`: Sets the generated SDK name and the UserAgent to `guru-sdk`.
+`--from-path`: Generates API calls from elements in `paths` instead of `components.schemas`.
 
 
-#### Generte the code
+#### Generate the Code
 
 Once this setup is complete, you can now use the Makefile. It's also a good idea to run ./configure --help, as it contains several useful options.
 - `--wget-json-search`: Helps with downloading `json-search`, which can be tricky to install, **If unsure, we recommend using this by default**

bin/README.md

@@ -25,19 +25,19 @@ This is also much faster than multiple calls to grep.
 This utility is used to check if osc-api.json has been generated correctly. It verifies that the file is a valid JSON and contains at least one API function.
 
 # path_to_snakecase
-snakecasise an object name.
-example `ReadVms` become `read_vms`
-`/my/{NAME}/getId` become `my_name_get_id`
+Converts an object name to snake_case.
+example `ReadVms` becomes `read_vms`
+`/my/{NAME}/getId` becomes `my_name_get_id`
 
 usage:
 ```
 ./path_to_snakecase STRING
 ```
 
 # path_to_camelcase
-camelcasise an object name.
-example `ReadVms` become `read_vms`
-`/my/{NAME}/getId` become `my_name_get_id`
+Converts an object name to camelCase.
+example `read_vms` become `ReadVms`
+`/my/{NAME}/getId` become `myNameGetId`
 
 usage:
 ```
@@ -46,7 +46,8 @@ usage:
 
 # get_argument_list
 
-Take an object componant in `paths` or in `components.schema`, and give a list of all it arguments.
+
+Retrieves an object component from `paths` or `components.schema` and returns a list of all its arguments.
 
 usage:
 ```
@@ -85,7 +86,8 @@ string
 
 # get_path_description
 
-Just return "" so far, as the api I test this with, had no description in the path
+
+Returns an empty string "" for now, as the API I tested this with had no description in the path.
 
 usage:
 ```
@@ -99,12 +101,11 @@ example:
 
 # arg_placement
 
-return where the argument is used.
-`path`, if the argument is use in the path
-`header` if it is an http header
-`query` if it is in a query string
-`data` if it is use in post data
-
+Return where the argument is used:
+`path`: If the argument is used in the URL path.
+`header`: If the argument is used as an HTTP header.
+`query`: If the argument is in a query string.
+`data`: If the argument is used in POST data.
 
 usage:
 ```
@@ -119,7 +120,7 @@ query
 
 # construct_path
 
-generate the C code to create a osc_str that the path of the call.
+Generate the C code to create an osc_str for the path of the call.
 
 example:
 
@@ -131,4 +132,4 @@ osc_str_append_string(&end_call, args->id);
 osc_str_append_string(&end_call, "/get");
 ```
 
-The code generated is not exhaustive, but you get the idea.
+The generated code is not exhaustive, but it conveys the general idea.