bitovi / documentjs Goto Github PK
View Code? Open in Web Editor NEWThe sophisticated documentation engine
Home Page: https://documentjs.com/
License: MIT License
The sophisticated documentation engine
Home Page: https://documentjs.com/
License: MIT License
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.
Disregard. Don't close. This is the last one. Sorry again for spam.
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
Include:
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.
The expando arrow doesn't work right in some cases. Check out:
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:
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.
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)
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
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;
}
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.
Originally here:
bitovi/canjs.com#189
Headings for signatures need id's so they can be linked to
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
If someone will update the template HTML, I'm happy to style it
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.
Generator breaks if @param {Object}
is followed by @option
. {{}}
works correctly
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.
@demo ../some/path/to/demo.html 1000
Height of 1000px isn't being set.
I'm not sure how to enable this, but this would be the killer feature for DocumentJS. Ideally, a user's workflow might be:
We as admins of the site should be able to see these changes as pull requests and automatically merge them.
YES
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
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:
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
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
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
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?
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.
All searches don't work in http://33.javascriptmvc.com/
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.
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
Using the command
documentjs/doc.bat crm
found in the JMVC documentation gives errors:
On Mac OS X 10.7.
I'm testing issue events on BitHub. Please disregard and please leave this issue open. Thanks.
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.
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.
Following the tutorial ( http://javascriptmvc.com/docs.html#!DocumentJS )
Please help!
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
Links to external content need to be active
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.
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.
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)
Problems I've encountered:
wait
wait
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:
Control
Control
Expected: to find the same result.
at
attr
att
attr
.Expected: to find attr
when the search term is attr
.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.