From 71ce6889d0a5359e63285d5ec3a299fd79b59778 Mon Sep 17 00:00:00 2001 From: Hsieh Chin Fan Date: Fri, 11 Oct 2024 21:30:23 +0800 Subject: docs: jsdoc --- src/Layout.mjs | 10 ++++++---- src/MenuItem.mjs | 16 +++++++++------- src/dumbyUtils.mjs | 13 ++++++------- src/dumbymap.mjs | 12 ++++++------ src/editor.mjs | 23 +++++++++++++---------- 5 files changed, 40 insertions(+), 34 deletions(-) (limited to 'src') diff --git a/src/Layout.mjs b/src/Layout.mjs index 1b5656d..485b513 100644 --- a/src/Layout.mjs +++ b/src/Layout.mjs @@ -94,7 +94,7 @@ export class Overlay extends Layout { /** * saveLeftTopAsData. * - * @param {} element + * @param {HTMLElement} element */ saveLeftTopAsData = element => { const { left, top } = element.getBoundingClientRect() @@ -105,7 +105,7 @@ export class Overlay extends Layout { /** * addDraggable. * - * @param {} element + * @param {HTMLElement} element */ addDraggable = element => { // Make sure current element always on top @@ -169,7 +169,8 @@ export class Overlay extends Layout { /** * enterHandler. * - * @param {} + * @param {HTMLElement} options.hemlHolder - Parent element for block + * @param {HTMLElement[]} options.blocks */ enterHandler = ({ htmlHolder, blocks }) => { // FIXME It is weird rect from this method and this scope are different... @@ -257,7 +258,8 @@ export class Overlay extends Layout { /** * leaveHandler. * - * @param {} + * @param {HTMLElement} htmlHolder + * @param {HTMLElement[]} blocks */ leaveHandler = ({ htmlHolder, blocks }) => { const resumeFromDraggable = block => { diff --git a/src/MenuItem.mjs b/src/MenuItem.mjs index 2fcb144..61ed33e 100644 --- a/src/MenuItem.mjs +++ b/src/MenuItem.mjs @@ -2,9 +2,9 @@ import { shiftByWindow } from './utils.mjs' /** * @typedef {Object} RefLink - * @property {string} ref -- name of link - * @property {string} link -- content of link - * @property {string|null} title -- title of link + * @property {string} ref - name of link + * @property {string} link - content of link + * @property {string|null} title - title of link */ /** @@ -204,7 +204,9 @@ export class Suggestion extends Item { /** * constructor. * - * @param {} + * @param {String} options.text + * @param {String} options.replace - new text content + * @param {CodeMirror} options.cm */ constructor ({ text, replace, cm }) { super({ text }) @@ -235,9 +237,9 @@ window.customElements.define('menu-item-suggestion', Suggestion, { extends: 'div /** * renderResults. return a menu item for reporting render results * - * @param {Object} options.modal -- Ojbect of plain-modal + * @param {Object} options.modal - Ojbect of plain-modal * @param {HTMLElement} options.modalContent - * @param {HTMLElement} map -- Rendered map element + * @param {HTMLElement} map - Rendered map element */ export const renderResults = ({ modal, modalContent }, map) => new Item({ @@ -366,7 +368,7 @@ export const toggleMapFocus = map => * getCoordinatesByPixels. * * @param {HTMLElement} map instance - * @param {Number[]} xy -- pixel of window + * @param {Number[]} xy - pixel of window */ export const getCoordinatesByPixels = (map, xy) => new Item({ diff --git a/src/dumbyUtils.mjs b/src/dumbyUtils.mjs index f0878cf..a449646 100644 --- a/src/dumbyUtils.mjs +++ b/src/dumbyUtils.mjs @@ -5,8 +5,7 @@ export const coordPattern = /^geo:([-]?[0-9.]+),([-]?[0-9.]+)/ /** * focusNextMap. - * - * @param {Boolean} reverse -- focus previous map + * @param {Boolean} reverse - focus previous map */ export function focusNextMap (reverse = false) { const renderedList = this.utils.renderedMaps() @@ -21,7 +20,7 @@ export function focusNextMap (reverse = false) { /** * focusNextBlock. * - * @param {Boolean} reverse -- focus previous block + * @param {Boolean} reverse - focus previous block */ export function focusNextBlock (reverse = false) { const blocks = this.blocks.filter(b => @@ -44,7 +43,7 @@ export function focusNextBlock (reverse = false) { * scrollToBlock. Smoothly scroll to target block. * If block is bigger than viewport, then pick strategy wisely. * - * @param {HTMLElement} block -- Scroll to this element + * @param {HTMLElement} block - Scroll to this element */ export const scrollToBlock = block => { const parentRect = block.parentElement.getBoundingClientRect() @@ -65,7 +64,7 @@ export function focusDelay () { /** * switchToNextLayout. * - * @param {Boolean} reverse -- Switch to previous one + * @param {Boolean} reverse - Switch to previous one */ export function switchToNextLayout (reverse = false) { const layouts = this.layouts @@ -297,9 +296,9 @@ const isAnchorVisible = anchor => { /** * addAnchorByPoint. * - * @param {point} options.point -- object has {x, y} for window coordinates + * @param {point} options.point - object has {x, y} for window coordinates * @param {HTMLElement} options.map - * @param {Function} options.validateAnchorName -- validate anchor name is OK to use + * @param {Function} options.validateAnchorName - validate anchor name is OK to use */ export const addAnchorByPoint = ({ defaultName, diff --git a/src/dumbymap.mjs b/src/dumbymap.mjs index 4405786..4cfc484 100644 --- a/src/dumbymap.mjs +++ b/src/dumbymap.mjs @@ -12,7 +12,7 @@ import PlainModal from 'plain-modal' import proj4 from 'proj4' import { register, fromEPSGCode } from 'ol/proj/proj4' -/** Selector of special HTML Elements */ +/** CSS Selector for main components */ const mapBlockSelector = 'pre:has(.language-map)' const docLinkSelector = 'a[href^="#"][title^="=>"]' const geoLinkSelector = 'a[href^="geo:"]' @@ -175,11 +175,11 @@ export const generateMaps = (container, { } }) - /** Create DocLinks */ + /** LINK: Create DocLinks */ container.querySelectorAll(docLinkSelector) .forEach(utils.createDocLink) - /** Add external symbol on anchors */ + /** LINK: Add external symbol on anchors */ container.querySelectorAll('a') .forEach(a => { if (a.href.startsWith('http') && !a.href.startsWith(window.location.origin)) { @@ -187,7 +187,7 @@ export const generateMaps = (container, { } }) - /** Set CRS and GeoLinks */ + /** LINK: Set CRS and GeoLinks */ register(proj4) fromEPSGCode(crs).then(projection => { const transform = proj4(crs, 'EPSG:4326').forward @@ -417,7 +417,7 @@ export const generateMaps = (container, { /** * updateAttributeByStep. * - * @param {Object} -- renderer which is running steps + * @param {Object} - renderer which is running steps */ const updateAttributeByStep = ({ results, target, steps }) => { let passNum = results.filter( @@ -442,7 +442,7 @@ export const generateMaps = (container, { * config converter for mapclay.renderWith() * * @param {Object} config - * @return {Object} -- converted config + * @return {Object} - converted config */ const configConverter = config => ({ use: config.use ?? 'Leaflet', diff --git a/src/editor.mjs b/src/editor.mjs index f6c7dab..a8e3e0d 100644 --- a/src/editor.mjs +++ b/src/editor.mjs @@ -9,9 +9,9 @@ import * as tutorial from './tutorial' /** * @typedef {Object} RefLink - * @property {string} ref -- name of link - * @property {string} link -- content of link - * @property {string|null} title -- title of link + * @property {string} ref - name of link + * @property {string} link - content of link + * @property {string|null} title - title of link */ // Set up Containers {{{ @@ -291,6 +291,7 @@ const updateScrollLine = (ele) => () => { } } +/** sync scroll from HTML to CodeMirror */ new window.MutationObserver(() => { clearTimeout(dumbyContainer.timer) dumbyContainer.timer = setTimeout( @@ -377,7 +378,7 @@ addClassToCodeLines() /** * completeForCodeBlock. * - * @param {Object} change -- codemirror change object + * @param {Object} change - codemirror change object */ const completeForCodeBlock = change => { const line = change.to.line @@ -436,8 +437,8 @@ const completeForCodeBlock = change => { /** * menuForEditor. * - * @param {Event} event -- Event for context menu - * @param {HTMLElement} menu -- menu of dumbymap + * @param {Event} event - Event for context menu + * @param {HTMLElement} menu - menu of dumbymap */ const menuForEditor = (event, menu) => { event.preventDefault() @@ -583,7 +584,7 @@ const insideCodeblockForMap = anchor => { /** * getLineWithRenderer. Get Renderer by cursor position in code block {{{ * - * @param {Object} anchor -- Codemirror Anchor Object + * @param {Object} anchor - Codemirror Anchor Object */ const getLineWithRenderer = anchor => { const currentLine = anchor.line @@ -686,7 +687,7 @@ const getSuggestionsFromAliases = option => /** * handleTypingInCodeBlock. Handler for map codeblock {{{ * - * @param {Object} anchor -- Codemirror Anchor Object + * @param {Object} anchor - Codemirror Anchor Object */ const handleTypingInCodeBlock = anchor => { const text = cm.getLine(anchor.line) @@ -703,7 +704,7 @@ const handleTypingInCodeBlock = anchor => { /** * getSuggestions. Get suggestions by current input {{{ * - * @param {Object} anchor -- Codemirror Anchor Object + * @param {Object} anchor - Codemirror Anchor Object */ const getSuggestions = anchor => { const text = cm.getLine(anchor.line) @@ -823,7 +824,7 @@ const getSuggestions = anchor => { /** * addSuggestions. Show element about suggestions {{{ * - * @param {Object} anchor -- Codemirror Anchor Object + * @param {Object} anchor - Codemirror Anchor Object * @param {Suggestion[]} suggestions */ const addSuggestions = (anchor, suggestions) => { @@ -1102,6 +1103,8 @@ dumbyContainer.onmousedown = (e) => { lineEnd.style.left = event.clientX + 'px' lineEnd.style.top = event.clientY + 'px' line.position() + + // TODO Scroll dumbymap.htmlHolder when cursor is at upper/lower side } context.classList.add('dragging-geolink') -- cgit v1.2.3-70-g09d2