docs: add js doc (#6)

Author: nobkd

src/bg/action.ts

@@ -4,7 +4,16 @@ import { matcher, runtimeMapUrl } from './bg';
 
 const replacedUrlMatcher = new RegExp(`^${runtimeMapUrl}\?`);
 
-browserAction.onClicked.addListener(async (tab: Tabs.Tab) => {
+/**
+ * Async function to react to clicks on the browser action icon.
+ * Takes the current tab, takes its hostname and inverts the state of the hostname.
+ *
+ * Requests all frames from the current tab, filters them for extension Leaflet frames and Maps frames.
+ * Reloads the full tab on extension Leaflet frame match.
+ * If no extension Leaflet frames were found it just reloads the Maps frames
+ * @param tab Currently active tab
+ */
+async function actionClick(tab: Tabs.Tab): Promise<void> {
     if (!tab.url || !tab.id) return;
 
     let hostname = getHostname(tab.url);
@@ -26,4 +35,6 @@ browserAction.onClicked.addListener(async (tab: Tabs.Tab) => {
             code: 'document.location.reload();',
         });
     });
-});
+}
+
+browserAction.onClicked.addListener(actionClick);

src/bg/bg.ts

@@ -10,6 +10,13 @@ export const matcher: RegExp = new RegExp(
 );
 export const runtimeMapUrl = runtime.getURL('map.html');
 
+/**
+ * Checks if `frames` send a request to Maps.
+ * If they do and the extension isn't disabled for the current site, then the request is redirected to the extension leaflet map with all URL search params.
+ * Else the request is'nt blocked.
+ * @param req Web Request from frame
+ * @returns Redirect to extension map or pass through if extension disabled for website
+ */
 function redirect(req: WebRequest.OnBeforeRequestDetailsType): WebRequest.BlockingResponse {
     // TODO: check if originUrl always matches current tab url -> e.g. in frames with subframes
     if (req.originUrl && req.url.match(matcher)) {
@@ -22,6 +29,7 @@ function redirect(req: WebRequest.OnBeforeRequestDetailsType): WebRequest.Blocki
     return {};
 }
 
+// Listens to web requests from frames, redirects when fitting `matcher`
 webRequest.onBeforeRequest.addListener(
     redirect,
     {
@@ -40,5 +48,5 @@ tabs.onActivated.addListener(updateActiveTabIcon);
 // listen for window switching
 windows.onFocusChanged.addListener(updateActiveTabIcon);
 
-// run at startup
+// update icon at startup
 updateActiveTabIcon();

src/bg/utils/actionIcon.ts

@@ -1,7 +1,11 @@
 import { browserAction, tabs } from 'webextension-polyfill';
 import { disabledHosts, getHostname } from './storage';
 
-export function updateIcon(hostname: string) {
+/**
+ * Updates the action icon
+ * @param hostname Hostname
+ */
+export function updateIcon(hostname: string): void {
     let disabled = disabledHosts.includes(hostname);
 
     browserAction.setIcon({
@@ -17,7 +21,10 @@ export function updateIcon(hostname: string) {
     });
 }
 
-export async function updateActiveTabIcon() {
+/**
+ * Async function to update the icon of the currently active tab. Uses `updateIcon` internally
+ */
+export async function updateActiveTabIcon(): Promise<void> {
     let browserTabs = await tabs.query({ active: true, currentWindow: true });
 
     let tab = browserTabs[0];

src/bg/utils/domainEnds.ts

@@ -1,3 +1,4 @@
+// Domain ends of google
 export const domainEnds: string[] = [
     'com',
     'ac',

src/bg/utils/storage.ts

@@ -3,17 +3,27 @@ import { updateIcon } from './actionIcon';
 
 export const KEY_DISABLED_HOSTS = 'disabled_hosts';
 
+// Listens to changes on the storage. Updates disabled hosts list, if stored list changes
 export let disabledHosts: string[] = await getDisabledHosts();
 storage.local.onChanged.addListener((changes) => {
     if (KEY_DISABLED_HOSTS in changes) {
         disabledHosts = changes[KEY_DISABLED_HOSTS].newValue ?? [];
     }
 });
 
+/**
+ * Async function to get the list of disabled hostnames
+ * @returns List of disabled hostnames
+ */
 async function getDisabledHosts(): Promise<string[]> {
     return (await storage.local.get(KEY_DISABLED_HOSTS))[KEY_DISABLED_HOSTS] ?? [];
 }
 
+/**
+ * Async function to invert the state of a hostname.
+ * Adds new entry if not disabled, removes entry, if already disabled
+ * @param hostname Hostname to invert the state of
+ */
 export async function invertHostState(hostname: string): Promise<void> {
     if (disabledHosts.includes(hostname)) {
         disabledHosts.splice(disabledHosts.indexOf(hostname), 1);
@@ -28,6 +38,11 @@ export async function invertHostState(hostname: string): Promise<void> {
     updateIcon(hostname);
 }
 
+/**
+ * Retrieves the hostname from a URL
+ * @param url Full URL string
+ * @returns Hostname string
+ */
 export function getHostname(url: string): string {
     url = url.replace(/^\w+:\/\//, '');
     url = url.split(/[\/#\?]/, 1)[0];

src/map/utils/parseDMS.ts

@@ -1,13 +1,22 @@
+/**
+ * Converts DMS coordinates to Lat and Lon
+ * @param input String containing DMS coordinates
+ * @returns Array containing Latitude and Longitude
+ */
 export function parseDMS(input: string): [number, number] {
     let parts: string[] = input.split(/[^\d\w\.]+/);
     let lat = convertDMSToDD(parts.slice(0, 4));
-    let lng = convertDMSToDD(parts.slice(4));
+    let lon = convertDMSToDD(parts.slice(4));
 
-    return [lat, lng];
+    return [lat, lon];
 }
-
-function convertDMSToDD(dmsd: string[]): number {
-    const [degrees, minutes, seconds, direction] = dmsd;
+/**
+ * Converts DMS part to Lat/Lon
+ * @param dms Array of four strings representing: Degree Minutes Seconds Direction
+ * @returns DMS part converted to Latitude / Longitude
+ */
+function convertDMSToDD(dms: string[]): number {
+    const [degrees, minutes, seconds, direction] = dms;
     let dd = Number(degrees) + Number(minutes) / 60 + Number(seconds) / (60 * 60);
 
     if (direction === 'S' || direction === 'W') {

src/map/utils/parsePB.ts

@@ -1,6 +1,25 @@
 export type TileType = 'roadmap' | 'satellite';
 export const tileTypes: TileType[] = ['roadmap', 'satellite'];
 
+/**
+ * Takes one bang operator and decodes it.
+ *
+ * Possible types are:
+ * - `s`: string
+ * - `v`: timestamp => keep as string
+ * - `b`: boolean? / byte? => keep as string
+ * - `f`: float
+ * - `d`: double
+ * - `i`: int
+ * - `m`: matrix => length as int
+ * - `e`: enum
+ * - `z`: base64 encoded coordinates => Degrees Minutes Seconds Direction
+ *
+ * Unknown types are kept as string.
+ *
+ * @param item One bang operator with the structure: position, one character (data type), encoded data
+ * @returns Array of two items. First is the decoded result. Second describes if the result is a new matrix.
+ */
 function convertType(item: string): [string | TileType | number, boolean] {
     item = item.replace(/^\d+/, '');
     const type: string = item.charAt(0);
@@ -29,6 +48,28 @@ function convertType(item: string): [string | TileType | number, boolean] {
     return [val, type === 'm'];
 }
 
+/**
+ * Half iterative half recursive function that converts an array of split hashbangs and converts it into a fitting representation.
+ * Multiple nested arrays possible.
+ *
+ * Example input:
+ * ```ts
+ * TODO: ['', '', '']
+ * ```
+ *
+ * Example result:
+ * ```ts
+ * TODO:
+ * ```
+ *
+ * References:
+ * - https://andrewwhitby.com/2014/09/09/google-maps-new-embed-format/
+ * - https://blog.themillhousegroup.com/2016/08/deep-diving-into-google-pb-embedded-map.html
+ * - https://stackoverflow.com/a/47042514
+ * @param items Bang operators (e.g. `!1m13`) split into pieces at `!`
+ * @param out Array for top and recursion levels to save results and return
+ * @returns Filled `out` array with bang operators converted into readable format
+ */
 export function parsePB(items: string[], out: any[] = []): any[] {
     let i = 0;
     while (i < items.length) {

src/map/utils/read.ts

@@ -24,11 +24,12 @@ export type MapData = {
     markers?: Marker[];
 };
 
+/**
+ * Decodes the `pb` parameter with the help of `parsePB` and `readQ`
+ * @param param Content of the `pb` parameter as a string
+ * @returns MapData with area, zoom, tile type and markers
+ */
 export async function readPB(param: string): Promise<MapData> {
-    // https://andrewwhitby.com/2014/09/09/google-maps-new-embed-format/
-    // https://blog.themillhousegroup.com/2016/08/deep-diving-into-google-pb-embedded-map.html
-    // https://stackoverflow.com/a/47042514
-
     let mapData: MapData = {
         markers: [],
     };
@@ -47,7 +48,7 @@ export async function readPB(param: string): Promise<MapData> {
     if (typeof currMarkers !== 'string') {
         for (let markers of currMarkers[0] as string[]) {
             if (markers.match(cidMatch)) {
-                // cid
+                // TODO: understand CID
                 console.log(markers);
             } else if (markers.match(dmsMatch)) {
                 let [lat, lon] = parseDMS(markers);
@@ -74,9 +75,14 @@ export async function readPB(param: string): Promise<MapData> {
     return mapData;
 }
 
+/**
+ * Makes a request to the Nominatim API to get the coordinates of an address
+ *
+ * Reference: https://medium.com/@sowmyaaji/how-to-build-a-backend-with-jquery-and-add-a-leaflet-js-frontend-e77f2079c852
+ * @param addr An address or place
+ * @returns The Latitude and Logitude of the address or place
+ */
 export async function readQ(addr: string): Promise<Marker | null> {
-    // https://medium.com/@sowmyaaji/how-to-build-a-backend-with-jquery-and-add-a-leaflet-js-frontend-e77f2079c852
-
     let uri = encodeURI(nominatimQ + addr);
     let res = await fetch(uri);
 

src/map/utils/zoom.ts

@@ -1,8 +1,13 @@
-// https://groups.google.com/g/google-earth-browser-plugin/c/eSL9GlAkWBk/m/T4mdToJz_FgJ
-
 const factor: number = 35200000;
 const precision: number = 10;
 
+/**
+ * Converts *altitude over the map* to *zoom level of the map*
+ *
+ * Reference: https://groups.google.com/g/google-earth-browser-plugin/c/eSL9GlAkWBk/m/T4mdToJz_FgJ
+ * @param alt Altitude as number
+ * @returns Zoom level between 0 and 19
+ */
 export function getMapZoom(alt: number): number {
     let zoom = Math.log2(factor / alt) * 1.225;
     zoom = Math.round((zoom + Number.EPSILON) * precision) / precision;

src/options/options.ts

@@ -8,12 +8,19 @@ import {
 
 const table = document.querySelector('.table')!;
 
-function buildEntries() {
+/**
+ * (Re)Builds the list of diasabled hostnames
+ */
+function buildEntries(): void {
     table.innerHTML = '';
     disabledHosts.forEach(createEntry);
 }
 
-async function addEntry() {
+/**
+ * Async function to add a hostname (from the form / URL Search Params) to the displayed list and the storage list of disabled hosts
+ * If the entry is already present in the stored hosts, no entry is added to the display list
+ */
+async function addEntry(): Promise<void> {
     const search = new URLSearchParams(document.location.search);
     let hostname = search.get('hostname');
     if (hostname === null) return;
@@ -25,7 +32,11 @@ async function addEntry() {
     createEntry(hostname);
 }
 
-function createEntry(hostname: string) {
+/**
+ * Creates a new entry for the displayed list of disabled hostnames and appends it to the view
+ * @param hostname Hostname to add to the list
+ */
+function createEntry(hostname: string): void {
     const div = document.createElement('div');
 
     let span = document.createElement('span');
@@ -38,7 +49,12 @@ function createEntry(hostname: string) {
     table.appendChild(div);
 }
 
-async function removeEntry(click: MouseEvent) {
+/**
+ * Async funtion to remove an entry at click of its button.
+ * Takes the index in the table to remove it from the list of stored hostnames
+ * @param click Button click
+ */
+async function removeEntry(click: MouseEvent): Promise<void> {
     let target: EventTarget | null = click.target;
     if (target === null) return;
 
@@ -48,7 +64,12 @@ async function removeEntry(click: MouseEvent) {
     await invertHostState(disabledHosts[index]);
 }
 
-function getIndex(button: HTMLButtonElement) {
+/**
+ * Gets the index of a list entry using its clicked button
+ * @param button Button that was clicked to remove an entry
+ * @returns Index of the list entry
+ */
+function getIndex(button: HTMLButtonElement): number {
     let div: HTMLDivElement = button.parentElement as HTMLDivElement;
     if (div === null) return -1;