bitovi / documentjs Goto Github PK

We need to update the template to allow TypeDefs to be displayed like this. The content is just for placeholder, so ignore the fact that it's not an actual TypeDef.
https://dl.dropboxusercontent.com/u/3843531/CanJS-TypeDefs-v2.jpg

• Move keyword/type (constructor) next to title
• Move path to top/right side
• Display typedef underneath title

If someone will update the template HTML, I'm happy to style it

OSX Snow Leopard
JMVC 3.0

If you have spaces in your current directory (example ~/Documents/Aptana Studio Workspace/) when executing documentjs/doc to generate documentation, it will fail with

documentjs/doc: line 28: /../steal/rhino/loader: No such file or directory

if I fix those with "$VAR" the documentjs/doc script works but then java fails with

Exception in thread "main" java.lang.NoClassDefFoundError: Studio
Caused by: java.lang.ClassNotFoundException: Studio
at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
at java.lang.ClassLoader.loadClass(ClassLoader.java:307)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
at java.lang.ClassLoader.loadClass(ClassLoader.java:248)

The Quick Start guide mentions this but doesn't seem to be implemented. This would be nice for us who like to document a little and then look at the changes.

If possible it would be nice if it could only regenerate the files that changed.

For pages that aren't part of a constructor that have an active link, the navigation screws up and shrinks the li tag, probably unintentionally.

Example image: http://i.imgur.com/VpHO9vg.png

Links to external content need to be active

New feature request which was raised in the JMVC forum here:

http://forum.javascriptmvc.com/#Topic/32525000000356005

Should work something like this:

load('steal/rhino/steal.js');
steal.plugins("documentjs").then(function(){
    DocumentJS('myapp/myapp.html', {
    ignore: /^jquery\/.*|^steal\/.*|^documentjs\/.*|^funcunit\/|^myapp\/resources\/.*|^myapp\/scripts\/.*/,
    });
});

I'll submit a pull request for this functionality soon

Cheers,
-adam

Include:

1. How to install
2. How to run
3. How to deploy to gh-pages

Disregard. Don't close. This is the last one. Sorry again for spam.

Other than the first item, ordering is okay. The first item seems consistently to be sent to the end. Viz.:

Currently parsing a js file without the @static directive results in an error:

js: "documentjs/libs/handlebars.js#1404(Function)", line 88: uncaught JavaScript runtime exception: TypeError: Cannot read property "name" from undefined

Issue in rhino(untested in node)

https://www.npmjs.org/search?q=documentjs

why not?

Following the tutorial ( http://javascriptmvc.com/docs.html#!DocumentJS )

• the first step works fine, the contents of "crm.js" are displayed on the docs.html
• adding customer.js and order.js in the second step, re-run the doc.bat and nothing changes on docs.html.

Please help!

If you click any Source link on 33.javascriptmvc.com/docs pages, it breaks. For example, click it here:

http://33.javascriptmvc.com/docs.html#!can.Model

It tries to bring you here:

http://33.javascriptmvc.com/undefined/blob/master/model/model.md#L8

When declaring a block as @function, the rendered view will output returns {undefined} if no @return line is specified. Not all functions return a value, requiring a @return destroys code clarity.

This happens when you select a thing in the sidebar that isn't in a static/prototype/plugins/pages/whatever group.

I'm not sure how to enable this, but this would be the killer feature for DocumentJS. Ideally, a user's workflow might be:

1. Go to a page, see an "edit this" button. Click it.
2. Login to github.
3. See an edit form for that page's markdown.
4. Make changes. Click "save".
5. See the updated changes. Be able to click "edit" and make other changes.

We as admins of the site should be able to see these changes as pull requests and automatically merge them.

Complications

What does a user see when they return to an edited page? Should they be able to see their branches that haven't been merged?

YES

• if they switch to that branch, can they make other edits? Can git switch branches and documentjs generate an HTML page fast enough to get a response out for every request. We might need to cache the docMap and be able to apply a single comments changes to it. This will involve:
  • checkout the branch
  • getting the file, pulling out the comment that has changed (this might be tricky if it doesn't have a clearly labeled name).
  • build the page for that comment using the cached docMap from the "clean" branch.

DocumentJS cannot be run standalone, because Steal is a dependency. Steal is not included in nor available as a download this Github repo.

Downloading Steal solves the issue, but I suggest either making the dependency more obvious in the documentation, or modifying this project to run independently from the Steal project.

My documentjs.json looks like this:

{
  "sites": {
    "docs": {
      "glob": "samsclub/public/app/**/*.{js,md}",
      "parent": "app",
      "out": "api"
    }
  }
}

When I run this from the same directory as the json file it outputs to ../docs. I expect to be in the current directory in the api folder.

Here's one place in jQuery++ (look at the title and subtitle):

Here's another in Tutorials:

This is how an optional @param is represented now:

<h4>timeout <code>{Number}</code></h4>

Here's how it should be:

<h4>timeout <code>{Number}</code><span class="optional">Optional</span></h4>

Along with this CSS:

.parameter .optional {
    float: right;
    font-size: 8pt;
    line-height: 20px;
}

When documenting the event listeners in my controllers I ran into the following issue. I try to document an event listener like this:

    /**
     * Changes the current [navAttr] route to the controller supplied in <code>el</code>'s
     * <code>data-controller</code> attribute.
     * 
     * @param {HTMLElement} el the element this event fired on
     */
    'li click': function(el) {
        $.route.attr(this.options.navAttr, el.data('controller'));
    }

Running the app/scripts/docs.js command on this runs fine. Howerver, when I look at the generated results, the documentation to this method is "unclickable" (i.e. nothing happens when I click on the item, except for an error in the JS console. See http://ge.tt/8dBpTZ9?c ). The problem seems to be related to the whitespace used in the definition, causing the link in the generated documentation to break.

Right now, can.util has a child @group called functions and some other children that aren't in a group. The sidebar will show "functions" as a regular item in the sidebar, not as a group. When you click on it, it selects the group title as if it was a normal item.

Problems I've encountered:

1. Be in FuncUnit
2. Search for wait
3. Find 3 results
4. Go to JQuery++ (or Home)
5. Search for wait
6. No results.

Expected: To find the same 3 results.

This might be intentional, but it's presented as one big docu, and I think people will expect the search to be global.

Another variation:

1. Be in CanJS API
2. Search for Control
3. Get 1 result
4. Go into can.Model
5. Search for Control
6. No results.

Expected: to find the same result.

1. Be in CanJS API -> can.Observe
2. Search for at
3. Note results include attr
4. Search to att
5. Results no longer include attr.

Expected: to find attr when the search term is attr.

When commenting a function, it is possible to define a @param as {Object}, yet no way to further define expected properties and attributes the function is expecting. As more developers shift to Objects to encapsulate parameters, we need a way to express Object.attribute in the @param

The current markdown converter (Showdown) doesn't support GitHub flavored markdown out of the box.

DocumentJS should use a better markdown parser like Marked (which is also faster) that supports it.

Generating documentation as described in the DocumentJS docs does not work, also reported here:

http://forum.javascriptmvc.com/#Topic/32525000000670170

I updated the tutorial already to create an index instead of a crm page but I am not sure why it doesn't load
the menu. Would it make sense to create separate DocumentJS pages instead of using the JavaScriptMVC
templates?

Generator breaks if @param {Object} is followed by @option. {{}} works correctly

As described in the docs, I created a crm directory with a crm.js file containing the following:

/*
 * @page index CRM
 * @tag home
 *
 * ###Little CRM
 *  
 * Our little CRM only has two classes:
 *  
 * * Customer 
 * * Order 
 */

Here is a screenshot of the results of my running the command documentjs/doc crm.

The scripts appear to be processed, and the JSON files are generated in crm/doc, but crm/docs.html is never created.

I'm using a fresh download of DocumentJS 3.2.2 on Mac OS X 10.7.2

can.grep and can.map are two functions i use commonly but they're not part of the published docs. There may be other similar helpers we want to make public.

The content under a signature / section does not feel like it belongs to it "strongly" enough. For example:

Any arguments passed to the construction function are passed to init and setup.

in

Check out how jQuery does it:

I'd like to group the content that belongs to a section better.

@demo ../some/path/to/demo.html 1000

Height of 1000px isn't being set.

In Can.EJS:

And then clicking render:

The sidebar changes. It seems disorienting; is this on pupose?

Using the command

documentjs/doc.bat crm

found in the JMVC documentation gives errors:

On Mac OS X 10.7.

When modifying comments written in any file, after running a build operation (documentjs/doc project) no changes are visible on the docs.html container.

Resolved by:

• Clearing the browser cache
• Testing dev documentation in browser private mode, start new session on revision.

I'm testing issue events on BitHub. Please disregard and please leave this issue open. Thanks.

At first it was pointing to a file that doesn't exist. When I changed that line to:

require('../node/generator');

... I could at least continue. However, then I got this:

Warning: path must be a string Use --force to continue.
TypeError: path must be a string
    at Object.fs.openSync (fs.js:427:18)
    at Object.fs.readFileSync (fs.js:284:15)
    at module.exports (/project-folder/node_modules/documentjs/node/generator/index.js:33:37)

Here is my Gruntfile:

generate: {
    "docs": {
        files: [{
            cwd: "<%= cfg.devFolder %>",
            src: ["**/*.js", "!test/**/*.js", "!vendors/**/*.js"],
            dest: "<%= cfg.sections.docs.docsFolder %>",
            expand: true
        }]
    }
}

Adding console.log(files, options.out) to the "generate" task, I get this:

[ 'private/components/app/app.js',
  'private/components/app/helpers/urls.js',
  'private/components/example/example.js',
  'private/init.js',
  'private/models/example/example.js' ]

// line break for clarity

docs/models/example/example.js

Also, please consider renaming the task to "documentjs".

There are a lot of complexities around making a multi-version documentation engine easy to use and configure. Here's my best attempt for a few use cases:

CanJS multi-version

• Be able to document and publish branches / tags, allowing us to have branch releases to experiment.
• Be able to work on (and watch) a local repo for quick verification.
• Use npm or bower for version number
• A slight miss-match between NPM / Tagged version and documentation (we sometimes improve/fix documentation after a release)

documentjs: {
     versions: {
        "1.1.8" : "https://github.com/bitovi/canjs/tree/1.1-legacy",
        "2.1.4" : "https://github.com/bitovi/canjs/tree/v2.1.4",
        "2.2.0-pre" : "https://github.com/bitovi/canjs/tree/minor",
        "2.2.0-dirty-checking" : "https://github.com/bitovi/canjs/tree/dirty-checking",
        "3.0.0-pre" : "https://github.com/bitovi/canjs/tree/major"
     },
     // ideally what would be automagically picked by the oldest version without cruft
     defaultVersion: "2.1.4",
     sourceDest: __dirname+"/<%= version%>/can"
     sites: {
        api: {
            src: ["*.md",''],
            ignore: ["guides"],
            dest: __dirname+"/{version}/api"
        },
        guides: {
            src: ["guides/*.md"],
            dest: __dirname+"/{version}/guides",
            "static" : [""],
            "templates" : [""]
        },
        site: {
            // root tells it to look somewhere other than the version location
            root: __dirname,
            src: ["_pages/*.md"],
            dest: __dirname+"/",
            "static" : [""],
            "templates" : [""]
        }
     }
}

To download every project and rebuild all the documentation, one would write:

grunt documentjs

However, it's VERY likely you don't want to do that over and over, and you have a version of canjs local. To document ONLY that local version:

grunt documentjs:../path/to/canjs/

If you need to give it a version:

grunt documentjs:../path/to/[email protected]

Finally, if you want to just build the API docs:

grunt documentjs:../path/to/[email protected]:api

• "sites" on project config is not document
• projectConfig doesn't show up
• link to http://documentjs.com/docs/DocumentJS.guides.documenting.html
• selected marker location
• tags not showing up
• @module doesn't link to type expression correctly

I've always wanted the ability to send someone a link like

http://33.javascriptmvc.com/docs.html#!page=can.Model&id=Listen

and have it scroll right to that section. This shouldn't be too hard to implement.

I dont really have time to re-post, so see original post at the jsmvc forums:
http://forum.javascriptmvc.com/topic/firefox-has-issues-with-main-website

All searches don't work in http://33.javascriptmvc.com/

I ran into a situation where I had a property named index that was really tough to figure out. Would be nice if there were warnings when it runs into a duplicate name.

It would be nice to be able to link to a type that is documented elsewhere on the web. For example you might have a function like:

@function xhr
@param {Object} options
@return {Promise} a promise that will resolve when the xhr is complete.

In which case you would want Promise to link to the MDN documentation. Perhaps "@Typelink" could do this:

@typelink Promise https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

The expando arrow doesn't work right in some cases. Check out:

http://canjs.com/docs/can.Observe.html

The way people have been writing their docu, it would make things easier if DocJS needed @description to be marked up explicitly and put unspecific blocks of text in @body. The way it is now, things go missing are are out of order if the @body tag is forgotten.

If the contents of the demo iframe are longer than the viewport allows, don't show the scroll bars as it looks ugly, at least in Windows.

Originally here:
bitovi/canjs.com#189

Headings for signatures need id's so they can be linked to

When running documentjs/doc project, if your project folder does not have docs at the root, the build script will fail.

Resolve by creating a docs folder in the project directory, and build again.