softwarebrothers / better-docs Goto Github PK

In the screenshot above, class Scheduler signature should be (abstract) Scheduler(initUrl, options opt) (a space between options and opt), as in the constructor signature right below it.

Please fix this issue soon. Many thanks!

I'm trying to use @component for my base component which is passed to say, a withFocusable higher-order function returns a higher-order component as below.
/**
*Item to render within List
*@component
*/
function ListItem(props){
// returns a JSX
}

ListItem.propTypes = {
/** Description for item */
item : PropTypes.object.isRequired,
index : PropTypes.number.isRequired,
forwardedRef: PropTypes.node
}
export default withFocusable(ListItem, {initialFocusId : 'item0'});

Generated document has only constructor section something like below and doesn't show any prop types section ( table ) or even these props with description.

ListItem
Item to render within List

Thanks in advance for this great package!
I have to admit that you are the best package for jsdocs which handles Typescript. Also you handle Vue components pretty well. But currently there is no way at all to handle vue components written in typescript.

consider this App.vue:

<template lang="html">
  <v-text-field
    label="Todo"
    placeholder="What do you have to do?"
    solo
    v-model="newTodo"
    @keydown.enter="addTodoItem"
  />
</template>

<script lang="ts">
import { Component, Vue } from 'vue-property-decorator';

@Component
export default class TodoForm extends Vue {
  newTodo: String = ""

  addTodoItem ():void {
    if (this.newTodo !== "") {
      //  ADD TODO
    }
  }
}
</script>

The package would fail to get the typescript code in the first place because it would fail to get the script out of the RegExp <script>(.*?)</script> in component.js because lang="ts" is used. and even if the RegExp was changed to <script.*?>(.*?)</script>, It would not try to parse it as Typescript.

I'm sure since both features already exists there would be great to have them work together. There is no other package or even a set of packages together that I know of that can accomplish that yet and it would be great if you were the first.

had to install "parcel" manually

FYI: im currently on a windows machine - if that is an issue

Started using the @component tag and was hoping there could be some new features:

Support for @ignore on a propType - sometimes certain props are connected to context/redux/hoc/etc and don't need a particular prop documented.

Ability to overwrite the prop "type" with a typedef or standard jsdoc type. PropTypes.shape, for instance isn't specific enough for some use cases.

Hi there.

I came across this repo though the category tag. Thanks for setting it up.

When I generate my docs, the description style doesn't get applied properly. On the example docs, the descriptions get style from the member.sass style.

In my generated docs, this style doesn't get applied because the description isn't wrapped in a <p> tag, but injected straight into the div. See the two attached screenshots.

Is this a problem with the template? My comments look the same as the in the example repo.

I use @component with react hooks and have all my methods listed under the main component.
How can useEffect here be added together with methods or which tag would be correct to use with useEffect?

There are some methods in a namespace. I want to show a menu listing all the method names on the right for quick searching. Just like below:

Hi

Could we please get support for sorting categories in lexical order? I.e if I have the following categories

Foo.Bar.Baz
Foo
Foo.Bar

then they should be presented in the following order

Foo
Foo.Bar
Foo.Bar.Baz

Thanks

Similar to #25 - I would like to be able to hook into Quasar components in my @components examples. My use case is however a bit more complicated, because I am using a Lerna monorepo with yarn workspaces and parsing all the packages (for JSDoc) from the root.

Here is an example:

<template lang="pug">
  q-input(
    outlined
    dense
    v-bind="$props"
    v-bind:value="value"
    v-on:input="$emit('input', $event)"
  )
</template>
<script>
/**
 * @component
 * @example
 * {
 *   template: `
 *     <MDInput class="q-my-md"
 *       v-model="email"
 *       type="email"
 *       label="Email"
 *       required
 *       autofocus
 *     />
 *   `,
 *   data: function() {
 *     return {
 *       email: '',
 *     }
 *   }
 * }
 */
export default {
  name: 'MDInput',
  props: ['value', 'label', 'type', 'autofocus', 'error', 'v-model']
}
</script>

Single-line comments are ignored

/**

• Comment is fine....
  */
  export interface IMyInterface {
  ...
  }

/**

• Comment is fine too.... */
  export interface IMyInterface {
  ...
  }

/** Comment is ignored... /
export interface IMyInterface {
/* this member comment also is also ignored */
isSuccess: boolean;
}

I am using TS with the syntax for type of data member:

enum NewEnumType{
   Value1,
   Value2,
}
interface newType {
       global?:{ [key in NewEnumType]?:any }
}

I am getting error in the doc generator like:
ERROR: Unable to parse a tag's type expression for source file /path/to/file/PublisherConfig.ts in line 56 with tag title "type" and text "{{ [key in ConfigurationGlobalOption]?:any }}": Invalid type expression "{ [key in ConfigurationGlobalOption]?:any }": Expected "!", "$", "'", "(", "*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", "}", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter, or [1-9] but "[" found.

How to solve it?

Hi,

I use better-docs for ReactJS with parcel and I have an issue relative to our Babel configuration.

I use an experimental syntax "classProperties" like that:

class Animal { 
  eat = () => {
    return this;
  };
}

An I have this error:

running: parcel build buildDocs/entry.js --out-dir buildDocs/build
🚨  /Users/ben/Documents/sources/repos/hellomybot/frontreact/src/components/CustomTable/CustomTable.jsx:79:14: Support for the experimental syntax 'classProperties' isn't currently enabled (79:15)

Usually this error can be corrected by using the babel plugin: @babel/plugin-proposal-class-properties (npm install). And with this configuration in .babelrc { "plugins": ["@babel/plugin-proposal-class-properties"] }.

However, I don't have the access to this file. Is it possible to edit it from the better-docs options in the jsdoc.json file?

BetterDocs 2.0.0 Proposal

Codebase Cleanup

• moving from jQuery to using native browser API's
  • http://youmightnotneedjquery.com/
• using const, and let vs var.
• removing the global state from publish.js and making it more functional and atomic, i.e., functions mutate, and return mutated inputs rather than altering the global state.
• remove readme folder, and remove images from the README
  • while these are nice, they take all the space above-the-fold, whereas it's always nice to have a project description in that space IMO. Demos could be provided on a jsdoc generated documentation page for the project using the project. See Dogfooding/Example below.
• rename static to public
  • remove all code in static
• move tmpl to public
• create public/assets and put the font-awesome heart icon into the folder
• move styles to src/styles
• move scripts to src/js, and update to use import syntax for use with Rollup
• remove third-party (vendor) JavaScript, e.g., prettify, and use npm.
• Use CDN for all third-party JS, and CSS.
• introduce preload, and prefetch in the head
• remove font-awesome and inline the heart icon as an SVG

Use .scss instead of .sass

• It's still SASS, just a modern, more familiar version of SASS which makes contributing easier. Also, CSS is valid SCSS.
• Using @extend to create base styles from which other styles can extend. This results in a performant stylesheet that renders all shared styles in single declaration blocks, and aberrant styles, i.e., one-off margin adjustments, etc. to their respective component blocks.
• Adding typography.scss
  • All font-related styles integrated into a single place
• removing third-party (vendor) CSS and use npm to ease the upgrade process for those vendor styles, e.g., prettify styles.

Migrate Build

• move from a Gulp based build system to using Rollup
• node-sass for building the styles.
  • gulp-sass plugin uses node-sass and is typically versions behind it. node-sass has a built-in CLI, so it makes it easier to stay up-to-date.
• Use Makefile to set up all the build tasks
  • Also willing to throw these into npm scripts. I have the Makefile already set up. 🤷‍♂️

More customization options, i.e., template overrides

• the layout seems essential to keep, but maybe split that up into header and footer templates, and slim down the layout?
• choose which side to put the mobile menu
  • right or left
• override individual templates
  • The default template allows overriding the layout, but maybe go further and allow the customization of individual template types? The effort requires some refactoring, and ideally, the template logic would remain out of the user's hands ideally and they would handle the markup (HTML)?

CLI

• prettify theme picker
  • npm install color-themes-for-google-code-prettify as a dependency
    • provide a default theme (tomorrow-dark?)
    • once the selection is chosen write the stylesheet to the current directory and provide instructions for including the stylesheet in the jsdoc configuration file betterDocs.prettifyTheme?
• eject functionality akin to create-react-app (post v2.0.0)
  • loads the templates, source files, and plugins into the user's directory.
  • This is just an idea, and one that I'm not completely sold on yet.
• hot reload server for doc development

Dogfooding/Example

i.e., host docs for better-docs on a JSDoc generated Github Pages site using the better-docs theme. This is a great way to demonstrate better-docs without having to use the admin tool you built.

I've already completed the codebase cleanup, the style migration and cleanup as well as the build migration. Working on the CLI in the next day or so. As I mentioned on Reddit, I was going to fork this project and start anew, but if you're willing to track this as a project here on your repository that would be awesome. If so we can cut a branch from master 2.0.0, create a Project (Kanban auto project setting), break these items down into individual tickets (issues), and then I can push what I have up to track against those tickets.

Hello,
In the example documentation (for AdminBro) you use @component tag to describe components and that is nice showed in sidebar (like modules, classes etc). Is this tag provided by some jsdoc's plugin? I really want to use it with my Vue.js project where I have a lot of components.

Migrate Build

• move from a Gulp based build system to using Rollup
• node-sass for building the styles.
  • gulp-sass plugin uses node-sass and is typically versions behind it. node-sass has a built-in CLI, so it makes it easier to stay up-to-date.
• Use Makefile to set up all the build tasks
  • Also willing to throw these into npm scripts. I have the Makefile already set up. 🤷‍♂️

The current @component tag only works with vue and react components, due to the way it is built, you need to partially re-program the tag for every web component framework.
instead there should be a more flexible @component tag whose attributes, proptypes, etc. are not derived from the code itself but are flat our written in the JSDoc comment.

More customization options, i.e., template overrides

• the layout seems essential to keep, but maybe split that up into header and footer templates, and slim down the layout?
• choose which side to put the mobile menu
  • right or left
• override individual templates
  • The default template allows overriding the layout, but maybe go further and allow the customization of individual template types? The effort requires some refactoring, and ideally, the template logic would remain out of the user's hands ideally and they would handle the markup (HTML)?

Given this reduced test case with a file named Cartesian3.ts:

/**
 * A 3D Cartesian point.
 */
class Cartesian3 {
    /**
     * The number of elements used to pack the object into an array.
     * @type {Number}
     */
    static packedLength = 3;
}

packedLength is listed twice in the generate doc:

Hi, it has two parcel error:

jsdoc.conf.json

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": ["jsdoc", "closure"]
  },
  "plugins": [
    "node_modules/better-docs/typescript",
    "node_modules/better-docs/component",
    "plugins/markdown"
  ],
  "source": {
    "include": ["src"],
    "includePattern": "\\.(jsx|js|ts|tsx)$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "better-docs": {
      "name": "My React components"
    }
  },
  "opts": {
    "template": "node_modules/better-docs",
    "encoding": "utf8",
    "destination": "jsdoc",
    "recurse": true,
    "verbose": true,
    "readme": "README.md"
  }
}

npm run docs --> "docs": "jsdoc -c jsdoc.conf.json",

Parsing C:\Users\Francisco\Documents\baikal-global\developers\src\components\SearchBar\index.tsx ...
Generating output files...
Generating entry file for "components" plugin
Bundling components
running: parcel build jsdoc\/entry.js --out-dir jsdoc\/build
"parcel" no se reconoce como un comando interno o externo,
programa o archivo por lotes ejecutable.

C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\bundler.js:83
    throw error
    ^

Error: Command failed: parcel build jsdoc\/entry.js --out-dir jsdoc\/build
"parcel" no se reconoce como un comando interno o externo,
programa o archivo por lotes ejecutable.

    at checkExecSyncError (child_process.js:630:11)
    at execSync (child_process.js:666:15)
    at bundle (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\bundler.js:78:5)
    at Object.exports.publish (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\publish.js:655:5)
    at Object.module.exports.cli.generateDocs (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:441:39)
    at Object.module.exports.cli.processParseResults (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:392:24)
    at module.exports.cli.main (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:235:18)
    at Object.module.exports.cli.runCommand (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:186:9)
    at C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\jsdoc.js:93:9
    at Object.<anonymous> (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:1158:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1178:10)
    at Module.load (internal/modules/cjs/loader.js:1002:32)
    at Function.Module._load (internal/modules/cjs/loader.js:901:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12)
    at internal/main/run_main_module.js:18:47 {
  status: 1,
  signal: null,
  output: [
    null,
    <Buffer >,
    <Buffer 22 70 61 72 63 65 6c 22 20 6e 6f 20 73 65 20 72 65 63 6f 6e 6f 63 65 20 63 6f 6d 6f 20 75 6e 20 63 6f 6d 61 6e 64 6f 20 69 6e 74 65 72 6e 6f 20 6f 20 ... 52 more bytes>
  ],
  pid: 14008,
  stdout: <Buffer >,
  stderr: <Buffer 22 70 61 72 63 65 6c 22 20 6e 6f 20 73 65 20 72 65 63 6f 6e 6f 63 65 20 63 6f 6d 6f 20 75 6e 20 63 6f 6d 61 6e 64 6f 20 69 6e 74 65 72 6e 6f 20 6f 20 ... 52 more bytes>
}

You need to add parcel as dependency.

×  C:\Users\Francisco\Documents\baikal-global\developers\jsdoc\entry.js:25:25: Cannot resolve dependency '../../C:UsersFranciscoDocumentaikal-globaldeveloperssrccomponentsFilterResultindex.tsx' at 'C:\Users\Francisco\Documents\baikal-global\C:UsersFranciscoDocumentaikal-globaldeveloperssrccomponentsFilterResultindex.tsx'
  23 |     import './styles/iframe.css';
  24 |
> 25 |   import Component0 from '../../C:\Users\Francisco\Documents\baikal-global\developers\src\components\FilterResult\index.tsx';
     |                         ^
  26 | reactComponents['FilterResult'] = Component0;
  27 |
  28 | import Component1 from '../../C:\Users\Francisco\Documents\baikal-global\developers\src\components\SearchBar\index.tsx';

C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\bundler.js:83
    throw error
    ^

Error: Command failed: parcel build jsdoc/entry.js --out-dir jsdoc/build
    at checkExecSyncError (child_process.js:630:11)
    at execSync (child_process.js:666:15)
    at bundle (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\bundler.js:78:5)
    at Object.exports.publish (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\better-docs\publish.js:655:5)
    at Object.module.exports.cli.generateDocs (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:441:39)
    at Object.module.exports.cli.processParseResults (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:392:24)
    at module.exports.cli.main (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:235:18)
    at Object.module.exports.cli.runCommand (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\cli.js:186:9)
    at C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\jsdoc.js:93:9
    at Object.<anonymous> (C:\Users\Francisco\Documents\baikal-global\developers\node_modules\jsdoc\jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:1158:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1178:10)
    at Module.load (internal/modules/cjs/loader.js:1002:32)
    at Function.Module._load (internal/modules/cjs/loader.js:901:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12)
    at internal/main/run_main_module.js:18:47 {
  status: 1,
  signal: null,
  output: [
    null,
    <Buffer c3 97 20 20 43 3a 5c 55 73 65 72 73 5c 46 72 61 6e 63 69 73 63 6f 5c 44 6f 63 75 6d 65 6e 74 73 5c 62 61 69 6b 61 6c 2d 67 6c 6f 62 61 6c 5c 64 65 76 ... 682 more bytes>,
    <Buffer >
  ],
  pid: 16608,
  stdout: <Buffer c3 97 20 20 43 3a 5c 55 73 65 72 73 5c 46 72 61 6e 63 69 73 63 6f 5c 44 6f 63 75 6d 65 6e 74 73 5c 62 61 69 6b 61 6c 2d 67 6c 6f 62 61 6c 5c 64 65 76 ... 682 more bytes>,
  stderr: <Buffer >
}
npm ERR! code ELIFECYCLE

You can fix with https://stackoverflow.com/questions/59809560/better-docs-creates-entry-js-file-incorrectly.

Codebase Cleanup

• moving from jQuery to using native browser API's
  • http://youmightnotneedjquery.com/
• using const, and let vs var.
• removing the global state from publish.js and making it more functional and atomic, i.e., functions mutate, and return mutated inputs rather than altering the global state.
• remove readme folder, and remove images from the README
  • while these are nice, they take all the space above-the-fold, whereas it's always nice to have a project description in that space IMO. Demos could be provided on a jsdoc generated documentation page for the project using the project. See Dogfooding/Example below.
• rename static to public
  • remove all code in static
• move tmpl to public
• create public/assets and put the font-awesome heart icon into the folder
• move styles to src/styles
• move scripts to src/js, and update to use import syntax for use with Rollup
• remove third-party (vendor) JavaScript, e.g., prettify, and use npm.
• Use CDN for all third-party JS, and CSS.
• introduce preload, and prefetch in the head
• remove font-awesome and inline the heart icon as an SVG

better-docs will use your .babelrc or inline babel config inside your jsdoc.json file like so:

"babel": {
        "presets": ["@babel/env"]
    },

to transpile your code but it ignores babel.config.js which is the suggested convention by babel 7 -- can we add support for this?

The package.json lists these 2 peer dependencies:

"react": "^0.16.0",
"react-dom": "^0.16.0",

Anyway React has no version matching the specified version rule.

Looking at the release history, React it jumps from 0.14.8 to 15.0.1 (16.13.0 being the current version at the time of writing).

Please fix the package.json. Thanks a lot.

As an example, the following URL shows the page containing the highlighted source code of a file Controller.js: https://sozi.baierouge.fr/api/Controller.js.html

Adding a URL hash to move to a specific line has no effect: https://sozi.baierouge.fr/api/Controller.js.html#line32
As a consequence, all links in the documentation that target a specific source line do not behave as expected.

The problem seems to be that linenumber.js runs before the source code has been highlighted.

It seems to be an issue with better-docs since the default JSDoc template works as expected.

Use .scss instead of .sass

• It's still SASS, just a modern, more familiar version of SASS which makes contributing easier. Also, CSS is valid SCSS.
• Using @extend to create base styles from which other styles can extend. This results in a performant stylesheet that renders all shared styles in single declaration blocks, and aberrant styles, i.e., one-off margin adjustments, etc. to their respective component blocks.
• Adding typography.scss
  • All font-related styles integrated into a single place
• removing third-party (vendor) CSS and use npm to ease the upgrade process for those vendor styles, e.g., prettify styles.

Hey Guys! I am currently working with the @category tag. Is there any functionality to create subcategories?

Example:

I have the categories "t.c" and "t.c.Bootstrap".

On the sidemenu, "t.c.Bootstrap" should be appear under "t.c" as a submenu.

Or if that isn't currently possible, is there any possibility to extend the sidemenu? Maybe with a custom sidemenu template?

The subtitle "Title" set in publish.js line 660 seems like a placeholder and cannot be edited.
I would prefer an empty string or a way to set it manually.

Hi, recently I updated one of my open source libraries and the documentation changed. It seems like right now the @category label is not working anymore.

Node.js version: 10.15.3
Npm version: 6.4.1
better-docs 1.3.0
jsdoc 3.6.3

Sample code: https://github.com/buccfer/aws-cognito-express
Sample generated doc: https://buccfer.github.io/aws-cognito-express/tutorial-01-quick-start.html

Thanks!

It says there's an unexpected token here:
https://github.com/turt2live/matrix-js-bot-sdk/blob/41eda8a224e2b63ad55659c805df28a9fc8521f5/src/appservice/Appservice.ts#L584

Parsing F:\Workspaces\matrix-misc\matrix-js-bot-sdk\src\appservice\Appservice.ts ...
ERROR: Unable to parse F:\Workspaces\matrix-misc\matrix-js-bot-sdk\src\appservice\Appservice.ts: Unexpected token (584:0)

The other is here:
https://github.com/turt2live/matrix-js-bot-sdk/blob/41eda8a224e2b63ad55659c805df28a9fc8521f5/src/appservice/MatrixBridge.ts#L53

Parsing F:\Workspaces\matrix-misc\matrix-js-bot-sdk\src\appservice\MatrixBridge.ts ...
ERROR: Unable to parse F:\Workspaces\matrix-misc\matrix-js-bot-sdk\src\appservice\MatrixBridge.ts: Unexpected token (53:24)

Finally, it explodes with the following when it hits its first interface (https://github.com/turt2live/matrix-js-bot-sdk/blob/41eda8a224e2b63ad55659c805df28a9fc8521f5/src/logging/ILogger.ts):

F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript\type-converter.js:84
  if (type.types && type.types.length) {
           ^

TypeError: Cannot read property 'types' of undefined
    at convertMembers (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript\type-converter.js:84:12)
    at statement.members.forEach.member (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript\type-converter.js:164:27)
    at Array.forEach (<anonymous>)
    at ast.statements.map.statement (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript\type-converter.js:154:27)
    at Array.map (<anonymous>)
    at typeConverter (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript\type-converter.js:134:25)
    at Parser.beforeParse (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\better-docs\typescript.js:27:21)
    at Parser.emit (events.js:189:13)
    at Parser._parseSourceCode (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\lib\jsdoc\src\parser.js:288:18)
    at Parser.parse (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\lib\jsdoc\src\parser.js:202:22)
    at Object.module.exports.cli.parseFiles (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\cli.js:365:46)
    at module.exports.cli.main (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\cli.js:234:18)
    at Object.module.exports.cli.runCommand.cb [as runCommand] (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\cli.js:186:9)
    at F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\jsdoc.js:93:9
    at Object.<anonymous> (F:\Workspaces\matrix-misc\matrix-js-bot-sdk\node_modules\jsdoc\jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:689:30)

Tested on both Windows and Ubuntu with the same results. It's quite possible that I've done some human error thing - if that's the case, please point me in the right direction :D

jsdoc.json:

{
  "tags": {
    "allowUnknownTags": true
  },
  "plugins": [
    "node_modules/better-docs/category",
    "node_modules/better-docs/typescript"
  ],
  "source": {
    "include": [
      "src"
    ],
    "includePattern": ".ts$"
  },
  "opts": {
    "encoding": "utf8",
    "destination": ".jsdoc",
    "readme": "README.md",
    "recurse": true,
    "verbose": true,
    "template": "node_modules/better-docs"
  }
}

Using command: jsdoc -c jsdoc.json -P package.json

Is there any plan to include search functionality in the better-doc template?, thanks for the amazing template

Thanks for your great work.

Please add an option to the config file to set the target option to parcel:
parcel-bundler/parcel#1571

There is an Apache license template in the prettify directory that looks more like a piece of instruction than a valid license document.

Does this belong to the prettify library and you are forced to include the license document this way?

(Using the @component plugin)

When a component is imported with a camel case name in a Vue file, for instance :

import iDownload from 'components/content/Download.vue';

I get in /docs/entry.js the corresponding line :

import i-download from '../src/components/content/Download.vue';

naturally breaking everything because quotes are missing around 'i-download'

Solution : add quotes to handle this (I think rather common) use case

When I add the tag @component in a React functional component description header and I ran the documentation generation I am getting the following error. Any idea of how the generated PATH got inserted \ in it

D:\git\nirvana\ui>yarn docs
yarn run v1.17.3
$ jsdoc -c jsdoc.conf.json
Generating entry file for "components" plugin
Bundling components
running: parcel build docs/entry.js --out-dir docs/build
×  D:\git\nirvana\ui\docs\entry.js:12:54: Bad character escape sequence (12:54)
  10 |
  11 |
> 12 |       import ReactWrapper from '../../D:\git\nirvana\ui\node_modules\better-docs/lib/react-wrapper.js';
     |                                                      ^
  13 |
  14 |       window.React = React;
  15 |

D:\git\nirvana\ui\node_modules\better-docs\bundler.js:83
    throw error
    ^

Error: Command failed: parcel build docs/entry.js --out-dir docs/build
    at checkExecSyncError (child_process.js:629:11)
    at execSync (child_process.js:666:13)
    at bundle (D:\git\nirvana\ui\node_modules\better-docs\bundler.js:78:5)
    at Object.exports.publish (D:\git\nirvana\ui\node_modules\better-docs\publish.js:655:5)
    at Object.module.exports.cli.generateDocs (D:\git\nirvana\ui\node_modules\jsdoc\cli.js:441:39)
    at Object.module.exports.cli.processParseResults (D:\git\nirvana\ui\node_modules\jsdoc\cli.js:392:24)
    at module.exports.cli.main (D:\git\nirvana\ui\node_modules\jsdoc\cli.js:235:18)
    at Object.module.exports.cli.runCommand.cb [as runCommand] (D:\git\nirvana\ui\node_modules\jsdoc\cli.js:186:9)
    at D:\git\nirvana\ui\node_modules\jsdoc\jsdoc.js:93:9
    at Object.<anonymous> (D:\git\nirvana\ui\node_modules\jsdoc\jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:776:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:787:10)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:829:12)
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Hi,

I use vue with typescript and annotations. I use these lib for the annotations :

• component : https://github.com/kaorun343/vue-property-decorator
• vuex : https://github.com/ktsn/vuex-class

When I run jsdoc, an error appear :

This is my jsdoc config :

{
  "tags": {
      "allowUnknownTags": true
  },
  "source": {
      "include": ["./src"],
      "includePattern": "\\.(js|jsx|ts|tsx|vue)$"
  },
  "plugins": [
      "plugins/markdown",
      "node_modules/better-docs/typescript",
      "node_modules/better-docs/category",
      "node_modules/better-docs/component"
  ],
  "opts": {
      "encoding": "utf8",
      "destination": "docs/",
      "recurse": true,
      "verbose": true,
      "readme": "./readme.md",
      "template": "node_modules/better-docs"
  },
  "templates": {
      "better-docs": {
          "name": "Kami-performance"
      }
  }
}

When i remove vue from this line :

"includePattern": "\\.(js|jsx|ts|tsx)$"

This work perfectly with all my ts files. i'dont know if this trouble is due at the annotation or at my vue files with typescript.

Version

• jsdoc : 3.6.3
• better-docs : 1.4.7
• typescript : 3.5.3
• vue : 2.6.10

This is probably a windows issue. Trying to use the @component tag results in this in entry.js

      import Wrapper from '..\node_modules\better-docs\lib\react-wrapper.js';

That should be

      import Wrapper from '../node_modules/better-docs/lib/react-wrapper.js';

The imports for the components have the same problem.

I have a Meteor app, and I'm getting this error when trying to document a React component with the @component tag for component files that import a Meteor package. Not sure whether this is an issue with something I'm doing, or better-docs, or Parcel...

unning: parcel build dev/docs/entry.js --out-dir dev/docs/build
🚨  /home/data/work/airsight/workspace/code/axldm/imports/ui/components/MaskEditor/Annotation.jsx:6:32: Cannot resolve dependency 'meteor/react-meteor-data'
  4 | import RK from 'react-konva';
  5 | import { Point, Polygon, Segment } from '@flatten-js/core'; 
> 6 | import { createContainer } from 'meteor/react-meteor-data';
    |                                ^
  7 | 
  8 | import RKMultiPolygon from './RKMultiPolygon';
  9 | import AnnotationInstanceLabels from './AnnotationInstanceLabels';

/home/data/work/airsight/workspace/code/axldm/node_modules/better-docs/bundler.js:83
    throw error
    ^

Error: Command failed: parcel build dev/docs/entry.js --out-dir dev/docs/build
    at checkExecSyncError (child_process.js:616:11)
    at execSync (child_process.js:653:13)
    at bundle (/home/data/work/airsight/workspace/code/axldm/node_modules/better-docs/bundler.js:78:5)
    at Object.exports.publish (/home/data/work/airsight/workspace/code/axldm/node_modules/better-docs/publish.js:655:5)
    at Object.module.exports.cli.generateDocs (/home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/cli.js:441:39)
    at Object.module.exports.cli.processParseResults (/home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/cli.js:392:24)
    at module.exports.cli.main (/home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/cli.js:235:18)
    at Object.module.exports.cli.runCommand.cb [as runCommand] (/home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/cli.js:186:9)
    at /home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/jsdoc.js:93:9
    at Object.<anonymous> (/home/data/work/airsight/workspace/code/axldm/node_modules/jsdoc/jsdoc.js:94:3)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
    at Function.Module.runMain (internal/modules/cjs/loader.js:742:12)

• prettify theme picker
  • npm install color-themes-for-google-code-prettify as a dependency
    • provide a default theme (tomorrow-dark?)
    • once the selection is chosen write the stylesheet to the current directory and provide instructions for including the stylesheet in the jsdoc configuration file betterDocs.prettifyTheme?
• eject functionality akin to create-react-app (post v2.0.0)
  • loads the templates, source files, and plugins into the user's directory.
  • This is just an idea, and one that I'm not completely sold on yet.
• hot reload server for doc development

I'm really enjoying better-docs - thanks so much for making it!

Is it possible to include components that have no props? For example, the following component does not appear in the generated docs without PropTypes.

/**
 * Some documented component
 * 
 * @component
 */
const Documented = () => {
  return (
    <div>Hello world</div>
  )
}

export default Documented

Thanks!

I would like to see an NPX example so I won't have to install this as a part of my project.

Thanks!

I have four scripts as part of the same module:

• get.js
• geyById.js
• post.js
• putById.js

The four begin as follows:
`/**

• Express Orders Controller
• @category Controllers
• @module Orders
  */`

The module page in the documentation starts correctly as follows:

But when the methods are finished, it starts again the description of all methods as in the beginning:

And this goes on for two more times, totaling four identical descriptions of all methods of the four files.

I'm new to jsdocs, so I'm not sure if this is what I did, having four files with the same module name is incorrect or if it's really a better-docs bug. In one way or another, I appreciate any help.

I think supporting vuetify components renderizantion, or at least, providing a way to manually register components globally would be awelsome.

🙏

(using @component plugin)

When a mixin is imported like this in a Vue file :

import userMixin from 'components/user/mixin'

it cannot be resolved (the script does not add /src/ before components/user/mixin), generating lots of lots and errors

Strangely, there are no errors of this kind with components import like this :

import Profile from 'components/user/Profile'

Hello! If you're using React, you should totally use react-live's editor component. It works on mobile, because it uses contenteditable for its editing abilities.

At the moment, I have trouble with the current editor in your docs on my phone (editors like Monaco, CodeMirror, and Ace, don't work on mobile).

Hi there,

It seems the parsing only works for propTypes that are defined in the component file itself. However, if the propTypes are defined in a separate file and imported into the component file, they do not seem to get picked up. Is it possible to add support for this scenario?

Tried the sample react component with proptypes. The example gets generated fine but required is 'No' even if isRequired is added to proptype.

`/**

• Some documented component
• @component
• @example
• const text = 'some example text'
• return (
• )
  */
  const Documented = (props) => {
  const { text } = props
  return (
  
  {text}
  
  )
  }

Documented.propTypes = {
/**
* Text is a text
*/
text: PropTypes.string.isRequired,
}

export default Documented`

This is my config

{ "tags": { "allowUnknownTags": true, "dictionaries": ["jsdoc"] }, "source": { "include": ["src"], "includePattern": ".+\\.js(doc|x)?$", "excludePattern": "(^|\\/|\\\\)_" }, "plugins": [ "plugins/markdown", "node_modules/better-docs/component", "node_modules/better-docs/category" ], "templates": { "better-docs": { "name": "My React components" } }, "opts": { "destination": "docs", "encoding": "utf8", "recurse": true, "verbose": true, "readme": "README.md", "template": "node_modules/better-docs/" } }

In lib/react-wrapper.js after executing this.executeScript() it creates window.component object with reference to all the components. Currently I see all of the components are undefined.

I've tried debugging looks like the source needs to be returned after concating.
https://github.com/SoftwareBrothers/better-docs/blob/master/lib/react-wrapper.js#L96

Something like this

try {\n        ").concat("return ", source, "\n      }

Dogfooding/Example

i.e., host docs for better-docs on a JSDoc generated Github Pages site using the better-docs theme. This is a great way to demonstrate better-docs without having to use the admin tool you built.