2d:null 2e:["$","title",null,{"children":"Lodash Documentation Generator | Nikita Sharov | Observable"}] 33:[] 31:{"id":"7a6cff9a998a58d2","slug":"lodash-documentation-generator","title":"Lodash Documentation Generator","thumbnail":"6d21c59bb2204ad81d5e569c558a9e80dae124266524bb96b086a6782c4f1862","access_level":"public","create_time":"$D2021-02-10T08:11:01.411Z","update_time":"$D2021-04-29T06:00:36.582Z","view_time":null,"first_public_time":"$D2021-02-17T14:50:47.495Z","has_unpublished_edits":null,"fork":{"id":"e730ff6a172a0126","slug":"whats-up-jsdoc","title":"What’s Up, JSDoc?","owner":{"id":"6c49d8d38db08400","login":"nikita-sharov","name":"Nikita Sharov"}},"stars":1,"starred":false,"owner":{"type":"team","id":"6c49d8d38db08400","login":"nikita-sharov","name":"Nikita Sharov","avatar_url":"https://avatars-next.observableusercontent.com/544afb614871e9f3bee546cbff7e689f2a454464b16ac434007893bde877f2df","tier":"starter_2024"},"version":9567,"publish_version":9567,"role":null,"authored":false,"authors":[{"type":"individual","id":"ee7c67b988c5530c","login":"nikita-sharov","name":"Nikita Sharov","avatar_url":"https://avatars-next.observableusercontent.com/544afb614871e9f3bee546cbff7e689f2a454464b16ac434007893bde877f2df","tier":null}],"members":[{"type":"individual","id":"ee7c67b988c5530c","login":"nikita-sharov","name":"Nikita Sharov","avatar_url":"https://avatars-next.observableusercontent.com/544afb614871e9f3bee546cbff7e689f2a454464b16ac434007893bde877f2df","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":3,"collection":{"id":"5b023cbcba5eec0d","slug":"lodash","title":"Lodash","owner":{"id":"6c49d8d38db08400","login":"nikita-sharov","name":"Nikita Sharov"}},"type":"notebook","body":{"title":"Lodash Documentation Generator","cells":[{"id":5952,"value":"md`# Lodash Documentation Generator\n\nFormatting [JSDoc](https://jsdoc.app/)-style comments like [D3 API documentation on GitHub](https://github.com/d3/d3/blob/master/API.md), \ntargeting the [most popular package](https://www.npmjs.com/package/lodash) on npm`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":505,"value":"_ = require(\"lodash@4\") // most recent per 2021-02-11","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":1444,"value":"// of the embedded major version\nmostRecentMinorPatch = _.VERSION // in MAJOR.MINOR.PATCH format ","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":544,"value":"smokeTests = md`---\n## Smoke tests\n\n- [Array](#arrayMethods)\n- [Collection](#collectionMethods)\n- [String](#stringMethods)\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":550,"value":"arrayMethods = md`### Array`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9399,"value":"_filter = compose(\"filter\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":744,"value":"_pull = compose(\"pull\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9402,"value":"_remove = compose(\"remove\", {spacing: Spacing.PRESERVE, tags: [\"returns\"]})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4214,"value":"_without = compose(\"without\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6186,"value":"collectionMethods = md`### Collection`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6189,"value":"_every = compose(\"every\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4229,"value":"stringMethods = md`### String`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4232,"value":"_escape = composeParagraphed(\"escape\", JsDocTag.RETURNS)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4234,"value":"_escapeRegExp = compose(\"escapeRegExp\", JsDocTag.RETURNS)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4236,"value":"_startsWith = compose(\"startsWith\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5459,"value":"data = md`---\n## Data`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5587,"value":"methodInfos = parse(annotatedSourceCode, commentBlocks)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":507,"value":"annotatedSourceCode = {\n const url = `https://cdn.jsdelivr.net/npm/lodash@${_.VERSION}/lodash.js` // claims to be faster than any other CDN\n return fetch(url).then(response => response.text());\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":7995,"value":"// see: https://www.npmjs.com/package/comment-parser\ncommentBlocks = {\n // requires specific version running into 502 (Bad Gateway Error) otherwise\n const parser = await require('https://bundle.run/comment-parser@1.1.4');\n const options = {\n startLine: 1, // one-based line numbers\n spacing: Spacing.PRESERVE // preserving line breaks (within @example and description)\n };\n \n return parser.parse(annotatedSourceCode, options); \n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5996,"value":"Spacing = ({\n COMPACT: \"compact\", // default\n PRESERVE: \"preserve\"\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5775,"value":"parse = async (sourceCode, commentBlocks) => {\n const repo = getSource(sourceCode);\n const annotationBlocks = _.filter(commentBlocks, isMethodAnnotationBlock); \n return _.map(annotationBlocks, commentBlock => createMethodInfo(commentBlock, repo));\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5725,"value":"getSource = (sourceCode) => {\n const lines = _.split(sourceCode, \"\\n\"); \n const getOneBasedLineNumber = (zeroBasedLineIndex) => _.add(zeroBasedLineIndex, 1);\n const createNumberedSource = (line, index) => {\n return {\n number: getOneBasedLineNumber(index), \n source: line\n };\n };\n \n const source = _.map(lines, createNumberedSource);\n const getZeroBasedLineIndex = (oneBasedLineNumber) => _.subtract(oneBasedLineNumber, 1);\n const getSource = (oneBasedLineNumber) => {\n const index = getZeroBasedLineIndex(oneBasedLineNumber);\n return source[index];\n }\n \n return {getSource, source};\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5866,"value":"createMethodInfo = (commentBlock, repo) => {\n const lineNumber = getFirstLineNumberAfter(commentBlock);\n const source = repo.getSource(lineNumber);\n return {\n name: getMethodName(source.source),\n comments: commentBlock,\n source: [source] \n };\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5786,"value":"getFirstLineNumberAfter = (commentBlock) => {\n const lastLineNumber = _.last(commentBlock.source).number;\n return _.add(lastLineNumber, 1);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5846,"value":"isMethodAnnotationBlock = (commentBlock) => {\n const memberOf = findTag(commentBlock, JsDocTag.MEMBEROF);\n if (_.isUndefined(memberOf)) {\n return _.stubFalse();\n }\n\n return _.eq(memberOf.name, \"_\") && \n includesTag(commentBlock, JsDocTag.SINCE);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9418,"value":"JsDocTag = ({\n MEMBEROF: \"memberof\",\n PARAM: \"param\",\n RETURNS: \"returns\",\n SINCE: \"since\"\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":3538,"value":"findTag = (commentBlock, tagName) => {\n const predicate = (tag) => _.eq(_.toLower(tag.tag), tagName);\n return _.find(commentBlock.tags, predicate);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5636,"value":"includesTag = (commentBlock, tagName) => {\n const tag = findTag(commentBlock, tagName);\n return _.isObject(tag);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":3649,"value":"getMethodName = (line) => {\n const regex = /(?:function (\\w+)\\()|(?:var (\\w+) = )/;\n const result = regex.exec(line);\n return result[1] ?? result[2];\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":187,"value":"getSourceUrl = (methodInfo) => {\n const lineNumber = _.first(methodInfo.source).number;\n return `https://github.com/lodash/lodash/blob/${_.VERSION}/lodash.js#L${lineNumber}`\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5916,"value":"standalonePackageExists = {\n const semver = await require(\"https://bundle.run/semver@7.3.5\") // semver parser used by npm\n const standalonePackageExists = async (methodName) => {\n if (semver.gte(_.VERSION, \"5.0.0\")) { \n return _.stubFalse(); // per method packages will be removed in v5\n }\n\n const packageName = getStandalonePackageName(methodName);\n const url = `https://api.npmjs.org/downloads/point/last-day/${packageName}`;\n const response = await fetch(url).then(response => response.json());\n return _.isUndefined(response.error); \n };\n \n return standalonePackageExists;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5917,"value":"getStandalonePackageName = (methodName) => `lodash.${_.toLower(methodName)}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":189,"value":"// see: https://lodash.com/per-method-packages\ngetStandalonePackageUrl = (methodName) => {\n const packageName = getStandalonePackageName(methodName);\n return `https://www.npmjs.com/package/${packageName}`;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":278,"value":"representation = md`---\n## Representation`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9468,"value":"composeParagraphed = async (methodName, ...tags) => compose(methodName, {spacing: Spacing.PRESERVE, tags})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":556,"value":"compose = createComposer(methodInfos)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5855,"value":"createComposer = (methodInfos) => { \n const keyValuePairs = _.map(methodInfos, d => [d.name, d]);\n const mapping = new Map(keyValuePairs);\n const methodNames = [...mapping.keys()];\n const defaults = {\n methodNames,\n spacing: Spacing.COMPACT,\n tags: []\n };\n \n const compose = async (methodName, options = {}) => {\n const methodInfo = mapping.get(methodName);\n let mergedOptions = _.cloneDeep(defaults);\n if (_.isString(options)) {\n mergedOptions.tags.push(options);\n } else {\n _.assign(mergedOptions, options);\n }\n \n return format(methodInfo, mergedOptions);\n };\n \n return compose;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":41,"value":"// for example embedding (as highlighted source code), see: https://github.com/observablehq/htl#node-values\nformat = async (methodInfo, options) => html`\n

\n ${await formatSynopsis(methodInfo)}\n ${formatDescription(methodInfo, options)}\n ${formatExample(methodInfo)}\n

`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":186,"value":"formatSynopsis = async (methodInfo) => {\n let literal = \"

\";\n literal += `#`;\n literal += ` ${formatSignature(methodInfo)}`;\n literal += ` · Source`;\n if (await standalonePackageExists(methodInfo.name)) {\n literal += `, Package`;\n }\n \n literal += \"

\";\n return literal;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9549,"value":"getDocumentationUrl = (methodName) => `#_${methodName}`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":91,"value":"// for similar signature format, see: https://docs.python.org/3.3/library/functions.html\nformatSignature = (methodInfo) => {\n const params = getParams(methodInfo.comments); \n return `_.${methodInfo.name}(${formatParams(params)})`;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":102,"value":"getParams = (commentBlock) => {\n const predicate = (tag) => _.eq(_.toLower(tag.tag), JsDocTag.PARAM);\n return _.filter(commentBlock.tags, predicate);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":99,"value":"formatParams = (params) => { \n let literal = _.stubString();\n let previousParam;\n for (const currentParam of params) {\n if (isObjectProperty(currentParam.name)) {\n continue;\n }\n \n if (currentParam.optional) {\n literal += \"[\"; \n } \n \n if (!_.isUndefined(previousParam)) {\n literal += \", \";\n }\n \n literal += `${currentParam.name}`;\n if (!_.isUndefined(currentParam.default)) {\n if (!_.eq(currentParam.default, \"[]\")) {\n literal += ` = ${formatDefault(currentParam.default)}`;\n }\n } \n\n literal += \"\"\n previousParam = currentParam; \n }\n \n const openSquareBracketCount = _.sumBy(literal, char => _.eq(char, \"[\"));\n if (_.gt(openSquareBracketCount, 0)) {\n literal += _.repeat(\"]\", openSquareBracketCount);\n }\n \n return literal;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6044,"value":"isObjectProperty = (paramName) => _.includes(paramName, \".\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":674,"value":"formatDefault = (value) => _\n .chain(value)\n .replace(\"-\", \" - \")\n .replace(\"[\", \"[\")\n .replace(\"]\", \"]\")\n .value()","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":197,"value":"formatDescription = (methodInfo, options) => {\n let text = _.trim(methodInfo.comments.description);\n text = removeNotePrefixes(text);\n \n if (_.includes(options.tags, JsDocTag.RETURNS)) {\n const tag = findTag(methodInfo.comments, JsDocTag.RETURNS);\n text += `\\n\\nReturns ${tag.description}`;\n }\n \n if (_.eq(options.spacing, Spacing.COMPACT)) {\n text = _.replace(text, /\\n\\n/g, \" \");\n }\n \n text = formatQuotedCharacters(text); \n text = removePeriodBeforeParenthesis(text);\n text = endWithPeriod(text);\n return formatText(text, methodInfo, options);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6166,"value":"removeNotePrefixes = (text) => _.replace(text, /\\*\\*Note:\\*\\* /g, _.stubString())","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6150,"value":"formatQuotedCharacters = (text) => {\n const regex = /\"([^\"])\"|'([^'])'/g;\n const replacer = (match, p1, p2) => `${_.escapeRegExp(p1 ?? p2)}`;\n return _.replace(text, regex, replacer);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":8123,"value":"removePeriodBeforeParenthesis = (text) => _.replace(text, \". (e.g.\", \" (e.g.\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6171,"value":"endWithPeriod = (text) => _.endsWith(text, \".\") ? text : `${text}.`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5970,"value":"formatText = (text, methodInfo, options) => {\n const paramNames = getParams(methodInfo.comments)\n .map(d => d.name);\n \n const renderer = createRenderer(paramNames, options.methodNames);\n marked.use({renderer}); // see: https://marked.js.org/using_pro\n return marked.parse(text);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":8048,"value":"createRenderer = (paramNames, methodNames) => {\n return {\n codespan: (code) => {\n if (_.includes(paramNames, code)) {\n return `${code}`;\n }\n \n const result = /(?:_.)([\\w.]+)/.exec(code);\n if (!_.isNull(result)) {\n const name = result[1];\n if (_.includes(methodNames, name)) {\n return `${name}`; // add prefix method\n }\n }\n \n return false; // use original codespan renderer\n }, \n link: (href, title, text) => { \n const pureText = _.replace(text, /|<\\/code>/g, _.stubString());\n return `${pureText}`; // ignoring title\n }, \n text: formatInvocationParams \n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":625,"value":"formatInvocationParams = (text) => {\n const regex = /:[ |\\n]\$(…?[A-z]+)(?:, (…?[|A-z]+))?(?:, (…?[A-z]+))?\$./;\n const replacer = (match, ...groups) => {\n const params = _\n .chain(groups)\n .slice(0, groups.length - 2) // 'offset' and 'string' arguments\n .filter(group => !_.isUndefined(group))\n .map(group => `${group}`)\n .join(\", \")\n .value();\n \n return `: (${params}).`;\n }; \n \n return _.replace(text, regex, replacer);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":8046,"value":"marked = {\n const marked = await require(\"marked@2\");\n marked.setOptions({smartypants: true}); // using \"smart\" typographic punctuation for things like quotes and dashes\n return marked;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":47,"value":"formatExample = (methodInfo) => {\n const example = findTag(methodInfo.comments, \"example\");\n if (_.isUndefined(example)) {\n return _.stubString();\n }\n \n return formatCode(example.description);\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":8114,"value":"// highlighting done by https://github.com/markedjs/marked, see: https://github.com/observablehq/stdlib#markdown\nformatCode = (block) => {\n return md`\n~~~js\n${block.trim()}\n~~~`;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W33","stdlib":"1","titling":"auto"}} 32:"$31:body"