weixin_39939668
weixin_39939668
2020-12-26 01:43

Idea: Show some default docs.

I ran documentjs, then serve docs and the page is just a blank index page, and I also don't see any pages that contain the documentation of the source files.

A nice default would be to show the package's README.md for the index page, and in the sidebar show links to pages where each page is the docs for a source file.

Try out dox-foundation and doxx to get an idea of what I mean.

该提问来源于开源项目:bitovi/documentjs

  • 点赞
  • 写回答
  • 关注问题
  • 收藏
  • 复制链接分享
  • 邀请回答

4条回答

  • weixin_39953481 weixin_39953481 4月前

    It does show a default like you say. Were any files found to process?

    Sent from my iPhone

    On Jan 21, 2015, at 10:27 PM, Joseph Orbegoso Pea notifications.com wrote:

    I ran documentjs, then serve docs and the page is just a blank index page, and I also don't see any pages that contain the documentation of the source files.

    A nice default would be to show the package's README.md for the index page, and in the sidebar show links to pages where each page is the docs for a source file.

    Try out dox-foundation and doxx to get an idea of what I mean.

    — Reply to this email directly or view it on GitHub.

    点赞 评论 复制链接分享
  • weixin_39939668 weixin_39939668 4月前

    Yeah, the output looks like this:

    
     ❯ documentjs                                                                                                                        [20:22:55]
    No documentjs.json. Create one to configure its behavior.
    Generating docs at ../docs
    FIND: Calendar.js
    FIND: Cube.js
    FIND: DoubleSidedPlane.js
    FIND: Grid.js
    FIND: Molecule.js
    FIND: Plane.js
    FIND: PushMenuLayout.js
    FIND: utils.js
    BUILD: Using cache documentjs/site/templates/99914b932bd37a50b983c5e7c90ae93b
    BUILD: Using cache documentjs/site/static/dist/99914b932bd37a50b983c5e7c90ae93b
    BUILD: Copying production files to ../docs/static
    Parent-less comments:.
    Guessed parent 'index'. Set parent in your siteConfig.
    OUT: ../docs/index.html
    

    So it found those source files, but only utils.js and Molecule.js have any documentation, but nothing is showing up for those. Those files look like this

    http://hastebin.com/ojawohepiv.js

    and

     js
    /*
     * LICENSE
     *
     * This Source Code Form is subject to the terms of the Mozilla Public
     * License, v. 2.0. If a copy of the MPL was not distributed with this
     * file, You can obtain one at http://mozilla.org/MPL/2.0/.
     *
     */
    
    import Engine from 'famous/core/Engine';
    
    export function contextWithPerspective(perspective) {
        var context = Engine.createContext();
        context.setPerspective(perspective);
        return context;
    }
    
    点赞 评论 复制链接分享
  • weixin_39953481 weixin_39953481 4月前

    So it found those source files, but only utils.js and Molecule.js have any documentation, but nothing is showing up for those.

    If the source for utils.js and Molecule.js looks like your hastebin, they don't have any documentation either, so nothing can and probably should show up. I don't think we should add a placeholder for files that don't have documentation.

    点赞 评论 复制链接分享
  • weixin_39939668 weixin_39939668 4月前

    Oops, haha, I forgot I stashed the changes. Here's the partially documented Molecule and here's utils.js:

     js
    /*
     *  Utility functions used by infamous.
     *
     * LICENSE
     *
     * This Source Code Form is subject to the terms of the Mozilla Public
     * License, v. 2.0. If a copy of the MPL was not distributed with this
     * file, You can obtain one at http://mozilla.org/MPL/2.0/.
     *
     */
    
    import Engine from 'famous/core/Engine';
    
    /*
     *  contextWithPerspective
     * Create a context with the given perspective.
     *
     *  {integer} perspective The amount of perspective to give the context.
     *  {famous/core/Context} The context with the applied perspective.
     */
    export function contextWithPerspective(perspective) {
        var context = Engine.createContext();
        context.setPerspective(perspective);
        return context;
    }
    

    But yeah, having empty placeholders would be a good idea. Also, some things could be inferred like function name, parameter names, etc, and just some generic placeholder docs can be generated. For example, by parsing Molecule.js without docs, documentjs could infer a Molecule and put that in the placeholder. Perhaps the result of inferring for a function would be equivalent to commenting {undefined} detectedParamName.

    Also, notice I used {famous/core/Context}, a path-based type which is not valid jsdoc format. jsdoctypeparser adds onto the jsdoc type syntax by allowing us to do {path: famous/core/Context}. Don't know if you're using jsdoctypeparser, but that feature is a good idea.

    点赞 评论 复制链接分享