Improve documentation 1 to implement 1

.vscode/settings.json

@@ -3,6 +3,10 @@
     "editor.fontLigatures": true,
     "editor.snippetSuggestions": "top",
     "editor.rulers": [80, 120],
+    "editor.formatOnSave": false,
+    "[typescript]": {
+        "editor.formatOnSave": true
+    },
     "terminal.integrated.fontFamily": "Consolas",
     "workbench.colorTheme": "Dracula Soft",
     "cSpell.ignoreWords": [

src/endpoints/apollo.ts

@@ -1,22 +1,22 @@
 //#region > Imports
-//> Apollo Client
-//#INSTALL "apollo-client"
+//#PACKAGE "apollo-client"
+//## npm install "apollo-client"@2.6.8
 // Contains the client for graphql handling
 import { ApolloClient } from "apollo-client";
-//> Apollo Link
-//#INSTALL "apollo-link-http"
+//#PACKAGE "apollo-link-http"
+//## npm install "apollo-link-http"@1.5.16
 // Contains the link for the apollo client
 import { HttpLink } from "apollo-link-http";
-//> Apollo Cache
-//#INSTALL "apollo-cache-inmemory"
+//#PACKAGE "apollo-cache-inmemory"
+//## npm install "apollo-cache-inmemory"@1.6.5
 // Contains cache handling for apollo
 import {
   InMemoryCache,
   IntrospectionFragmentMatcher,
   NormalizedCacheObject,
 } from "apollo-cache-inmemory";
-//> Interfaces
-//#INSTALL "graphql"
+//#PACKAGE "graphql"
+//## npm install "graphql"@14.6.0
 // Contains the interface for gql queries, mutations and subscriptions
 import { DocumentNode } from "graphql";
 
@@ -25,7 +25,7 @@ import { ApolloEndpoint, IOptions } from "./index";
 //#endregion
 
 //#region > Classes
-/** @class Apollo client for graphql handling. */
+/** @class Apollo client for graphql handling */
 class Apollo implements ApolloEndpoint {
   //> Fields
   private link: HttpLink;
@@ -36,12 +36,10 @@ class Apollo implements ApolloEndpoint {
   desc: string = "A endpoint used for APIv4 requests";
 
   /**
-   * Creates a Apollo instance.
-   *
    * @constructor
    * @author Nico Schett <contact@schett.net>
-   * @param uri A uri of a graphql endpoint.
-   * @param options Configuration options.
+   * @param uri A uri of a graphql endpoint
+   * @param options Configuration options
    */
   constructor(uri: string, options: IOptions) {
     this.headers = options.headers;
@@ -79,6 +77,18 @@ class Apollo implements ApolloEndpoint {
   }
 
   //> Methods
+  /**
+   * Send: Provides requests for various graphql types.
+   *
+   * @param {string} type The type of the action you want to perform like Query,
+   *                      Mutation,...
+   * @param {DocumentNode} data The query structure
+   * @param {object} variables A object which contains variables for the query
+   *                           structure.
+   * @param {object} headers Optional headers which get appended to the endpoint
+   *                         headers.
+   * @returns {Promise<object>} Resolved apollo data object
+   */
   async send(
     type: string,
     data: DocumentNode,

src/endpoints/index.ts

@@ -1,12 +1,13 @@
 //#region > Imports
 //> Interfaces
-//#INSTALL "graphql"
+//#PACKAGE "graphql"
+//## npm install "graphql"@14.6.0
 // Contains the interface for gql queries, mutations and subscriptions
 import { DocumentNode } from "graphql";
 //#endregion
 
 //#region > Interfaces
-/** @interface Endpoint defines the basic endpoint structure. */
+/** @interface Endpoint defines the basic endpoint structure */
 interface IEndpoint {
   /**
    * Hedaers: A object which contains the headers as key value pair.
@@ -18,24 +19,27 @@ interface IEndpoint {
   desc: string;
 }
 
-/** @interface Options defines the structure of the apollo options. */
+/** @interface Options defines the structure of the apollo options */
 interface IOptions {
   /**
    * Headers: Contains the headers for the requests.
    */
   headers: object;
 }
 
-/** @interface ApolloEndpoint defines the structure of the apollo endpoint. */
+/** @interface ApolloEndpoint defines the structure of the apollo endpoint */
 interface ApolloEndpoint extends IEndpoint {
   /**
    * Send: Provides requests for various graphql types.
    *
-   * @param {string} type The type of the action you want to perform. Query, Mutation,...
-   * @param {DocumentNode} data The query structure.
-   * @param {object} variables A object which contains variables for the query structure.
-   * @param {object} headers Optional headers which get appended to the endpoint headers.
-   * @returns {Promise<object>} Resolved apollo data object.
+   * @param {string} type The type of the action you want to perform like Query,
+   *                      Mutation,...
+   * @param {DocumentNode} data The query structure
+   * @param {object} variables A object which contains variables for
+   *                           the query structure.
+   * @param {object} headers Optional headers which get appended to
+   *                         the endpoint headers.
+   * @returns {Promise<object>} Resolved apollo data object
    */
   send: (
     type: string,
@@ -45,20 +49,20 @@ interface ApolloEndpoint extends IEndpoint {
   ) => Promise<object>;
 }
 
-/** @interface ScraperEndpoint defines the structure of the scraper endpoint. */
+/** @interface ScraperEndpoint defines the structure of the scraper endpoint */
 interface ScraperEndpoint extends IEndpoint {
   /**
    * GetJson: A method which gets json data from a specific url.
    *
-   * @param url A web url.
-   * @returns {Promise<T>} Json data in the given format <T>.
+   * @param url A web url
+   * @returns {Promise<T>} Json data in the given format <T>
    */
   getJson<T>(url: string): Promise<T>;
   /**
    * GetDom: A method which gets DOM data from a specific url.
    *
-   * @param url A web url.
-   * @returns {Promise<Document>} A DOM Document.
+   * @param url A web url
+   * @returns {Promise<Document>} A DOM Document
    */
   getDom(url: string): Promise<Document>;
   /**

src/endpoints/scraper.ts

@@ -5,41 +5,44 @@ import { ScraperEndpoint, IOptions } from "./index";
 //#endregion
 
 //#region > Classes
-/** @class A endpoint to fetch page DOM. */
+/** @class A endpoint to fetch page DOM */
 class Scraper implements ScraperEndpoint {
   //> Fields
   headers: object = {
     accept: "application/json, text/plain, */*",
   };
+
   desc: string = "A endpoint to fetch page DOM";
   proxy: string = "https://cors.snek.at/";
 
   /**
    * @constructor
    * @author Nico Schett <contact@schett.net>
-   * @param root Root url of endpoint. Specify it like https://foo.bar. The correct placement of the slashes is
-   *             essential!
-   * @param options Specify options object to define e.g headers.
-   * @description Creates a instance of Scraper.
+   * @param root Root url of endpoint. Specify it like "https://foo.bar".
+   *             The correct placement of the slashes is essential!
+   * @param options Specify options object to define e.g headers
    */
   constructor(private root: string, options: IOptions) {
     this.headers = { ...this.headers, ...options.headers };
   }
 
   //> Getter
   /**
+   * Provides a URL which is composed of proxy and root url.
+   *
    * @returns {string} A URL
-   * @description Provides a URL which is composed of proxy and root url
    */
   get url(): string {
     return this.proxy + this.root;
   }
 
   //> Methods
   /**
-   * @param path Path to the endpoint. Specify it like "/foo/bar". The correct placement of the slashes is essential!
-   * @returns {T} JSON object passed to given structure <T>.
-   * @description Get JSON object<T> from specified path.
+   * Get JSON object from specified path.
+   *
+   * @param path Path to the endpoint. Specify it like "/foo/bar".
+   *             The correct placement of the slashes is essential!
+   * @returns {T} JSON object passed to given structure
    */
   async getJson<T>(path: string): Promise<T> {
     return fetch(this.url + path, {
@@ -57,9 +60,11 @@ class Scraper implements ScraperEndpoint {
   }
 
   /**
-   * @param path Path to the endpoint. Specify it like "/foo/bar". The correct placement of the slashes is essential!
-   * @returns {object} DOM object.
-   * @description Get DOM object from specified path.
+   * Get DOM object from specified path.
+   *
+   * @param path Path to the endpoint. Specify it like "/foo/bar".
+   *             The correct placement of the slashes is essential!
+   * @returns {object} DOM object
    */
   async getDom(path: string): Promise<Document> {
     return fetch(this.url + path, {
@@ -80,11 +85,12 @@ class Scraper implements ScraperEndpoint {
   }
 
   /**
+   * Post data to a endpoint and get the respective result.
+   *
    * @param {string} path Path to the endpoint. Specify it like "/foo/bar".
    *                      The correct placement of the slashes is essential!
    * @param data Data which is filled into the body of a post request
    * @returns {Promise<Document>} A DOM Document
-   * @description Post data to a endpoint and get the respective result
    */
   async post<T>(
     path: string,

src/index.ts

@@ -8,7 +8,7 @@ import Scraper from "./endpoints/scraper";
 // Contains the main template
 import { MainTemplate } from "./templates/index";
 //> Sessions
-// Contains the snek and github session
+// Contains the SNEK and github session
 import { SnekSession, GithubSession } from "./session/sessions";
 //> Interfaces
 // Contains interfaces for scraper and apollo
@@ -18,27 +18,37 @@ import { IMainTemplate } from "./templates/index";
 //#endregion
 
 //#region > Interfaces
-/** @interface Endpoint defines the structure of object a endpoint requieres to initialize. */
+/**
+ * @interface Endpoint defines the structure of object a endpoint requirers to
+ *                     initialize.
+ */
 interface IEndpoint {
   /**
-   * Url: the URL of an endpoint. For performance reasons,
+   * Url: The URL of an endpoint. For performance reasons,
    *      https should always be selected as protocol if possible.
    */
   url: string;
+  /**
+   * Type: It is possible to specify the type. This is currently only used to
+   *       differentiate multiple instances.
+   */
   type: string;
   headers: object;
 }
 
-/** @interface Client will define the client structure. */
+/** @interface IClient will define the client structure */
 interface IClient {}
 //#endregion
 
 //#region > Classes
-/** @class The snek-client. Enjoy it. Will be implemented in the future. */
+/**
+ * @class The SNEK-client. Enjoy it. Will be implemented in the future
+ * @todo Rework the url checker and add documentation
+ */
 class Client implements IClient {
   constructor(ep: IEndpoint) {
     /*
-     * When no protocol is defined, http will be appended. Therefore https
+     * When no protocol is defined, http will be appended. Therefore "https"
      * should always be included for performance.
      */
     ep.url = ((url: string) => {
@@ -51,12 +61,20 @@ class Client implements IClient {
   }
 }
 
-/** @class A client implementation for snek interaction. */
+/** @class A client implementation for SNEK interaction */
 class SnekClient extends Client {
   endpoint: ApolloEndpoint;
   template: IMainTemplate;
   session: SnekSession;
 
+  /**
+   * @constructor
+   * @author Nico Schett <contact@schett.net>
+   * @param url The base URL the SnekClient should be working on.
+   *            Default: "https://engine.snek.at/api/graphiql".
+   * @param headers A object containing various request headers
+   * @param type A type description to differ between multiple instances
+   */
   constructor(
     url: string = "https://engine.snek.at/api/graphiql",
     headers: object = {},
@@ -70,12 +88,20 @@ class SnekClient extends Client {
   }
 }
 
-/** @class A client implementation for github interaction. */
+/** @class A client implementation for github interaction */
 class GithubClient extends Client {
   endpoint: ApolloEndpoint;
   template: IMainTemplate;
   session: GithubSession;
 
+  /**
+   * @constructor
+   * @author Nico Schett <contact@schett.net>
+   * @param url The base URL the GithubClient should be working on.
+   *            Default: "https://api.github.com/graphql".
+   * @param headers A object containing various request headers
+   * @param type A type description to differ between multiple instances
+   */
   constructor(
     url: string = "https://api.github.com/graphql",
     headers: object = {},
@@ -96,6 +122,13 @@ class GithubClient extends Client {
 class WebClient extends Client {
   public scraper: ScraperEndpoint;
 
+  /**
+   * @constructor
+   * @author Nico Schett <contact@schett.net>
+   * @param url The base URL the WebClient should be working on
+   * @param headers A object containing various request headers
+   * @param type A type description to differ between multiple instances
+   */
   constructor(
     url: string,
     headers: object = {},