hegemonic/jsdoc-baseline

An experimental, extensible template for JSDoc.

jsdoc-baseline's Issues

Add "generated by" footer

With an option to disable it.

Lint LESS source file(s)

Using gulp-recess.

Tests!

• Add test framework (including Istanbul)
• Add unit tests for JS code
• Figure out how to test Swig templates
• Write template tests

Make sure mixins appear in module view

Like: jsdoc/jsdoc@c1617b8

Optionally show (some of) the dl-list stuff in a panel

Should be separately configurable for top-level symbols and methods/properties/etc.

Improved handling of overloaded constructors

Right now, if a class has an overloaded constructor, I think we show all of the page content once per variation in symbol.swig. That's not so great.

One way to handle this:

1. Assume all the variations (contained in docs) have the same members.
2. Coalesce the header info for all the variations.
3. Show the members for the first variation.

This isn't perfect, but it should handle most use cases.

Are there other times when we're likely to pass more than one item in the docs array? If so, need to handle those too.

Handle default values that are object or array literals

Like: jsdoc/jsdoc@8128dc5

Option to display callbacks/typedefs alongside method parameters

If you're using the @callback or @typedef tag, there are times when you might want to show the type info near (or inline with) the places where you use those type definitions.

As a starting point, this will probably just be a global, on-or-off toggle, but try to think about finer-grained ways to do this. (For example: Based on how many times it's used? Based on whether you're looking at the same page where the type is documented? Based on some new tag?)

Create gulp task to auto-upgrade a customized version of the template

For each file, at a minimum:

• Check "last updated" version
• Warn about anything that can't be auto-upgraded because it's missing the "last version" annotation
• Warn about anything that can't be auto-upgraded because it's been customized

Questions:

• How to track template delta between versions? How do we know what to upgrade from version 0.x to 0.y?
• Okay to upgrade from 0.x to 0.y by doing all the stepwise upgrades in between? Or is there a better way?

Enable line numbering w/o separate script

I think Prettify supports this...

Style the TOC

And maybe redo JS?

Display enums on Global page

Right now we don't.

Add optional jump-to-symbol dropdowns

Ideally with an autocomplete field.

Commit static files, and add their license info

Like the summary says.

Add option to separate static/instance members

And option whether to show all static first, then all instance (or vice-versa), or to interleave static/instance properties, then static/instance methods, etc.

Remove namespaces from names in page titles

For example, use foo instead of module:foo.

Source file page titles start with the word "Tutorial"

Update CSS build process to strip unused rules

See:

• http://addyosmani.com/blog/removing-unused-css/
• https://github.com/ben-eb/gulp-uncss

This will require very thorough test cases, lest we strip styles that are actually necessary.

Show mixins for everything, not just classes and modules

Like: jsdoc/jsdoc@19867a0

Living style guide

Possibly with kss-node.

Create gulp task to generate a list of blocks in Swig templates

Ideally it would look tree-like and show inheritance/overrides.

Test performance with precompiled Swig templates

Blocked by #1.

Pull in less of Bootstrap

We're only using a fraction of it.

Module-page bugs

These all happen if you have something like module.exports = 2;:

• Description doesn't show up
• No type info when module.exports is not a function/constructor
• "Defined in" appears twice

Should check these for functions, too. Also, check for other issues that were fixed in jsdoc/jsdoc@8c66aef.

Add at least one alternate stylesheet that uses a non-Bootstrap framework

Partly for variety, partly to verify that everything works as expected.

Revisit mechanism for mapping CSS classes

Could do it by extending classes in LESS, right?

If not, gulp-themer may be helpful.

Use namespace for helper functions?

Do we need to use a namespace for all the helper functions, so things aren't clobbered if someone has a method called log or what have you?

Need to investigate and implement if necessary.

Source file pages should have a top-level heading

Generate source files by default, with option to disable

Like: jsdoc/jsdoc@39daa9a

Create Yeoman generator for a customized version of the template

Try to anticipate what will be needed to auto-upgrade the skeleton in the future (e.g., some sort of "last updated" version annotation).

Hide default values for enums

If we don't already.

Like: jsdoc/jsdoc@6e940d2

Minify CSS/JS static files

Probably as a gulp task, but maybe at runtime.

I18N/L20N support

Extract hard-coded text into resource files. Maybe use newspeak.

Add "Global" link to TOC when needed

Display Closure Compiler type info more effectively

First crack at this was jsdoc/jsdoc@254dda5

Improve the gulpfile

• Build compiled versions of the Swig templates
• Add a default task
• Consider adding a task to copy static files to an existing output directory

Config file mechanism

Add one, and convert things to use it as needed.

Split up publish.js

Add optional client-side search tool

At least for the names of methods, properties, classes, and so on, if not full text.

Maybe lunr.js for full-text search?

Put something useful on the index page

Fix issues with properties

• Show properties on symbol pages
• Show properties on global page
• Support properties with properties, like: jsdoc/jsdoc@5c59bc1
• Make sure enums show up

BiDi support

Maybe with gulp-css-flip?

Add options for summarizing the page

At least two:

• Summary section at the top of the page, a la Javadoc
• All sections collapsed by default, a la various other doc generators

Try Noto Sans

Wasn't aware of this one when I picked the current fonts:

http://www.google.com/get/noto/#/family/noto-sans

Add cssClass helper to every conceivable place where it might be useful

Even if we're not using it by default in most cases.

Add option to distinguish between static and instance members in headings

For example, Foo.bar() is static and baz() is instance.

Fix heading levels in text (especially descriptions and the README)

This isn't as easy as replacing all <h#> tags with {% h %}, because the user might have included subheadings. We probably need to find all the HTML heading tags, then adjust their level based on what we'd use for the Swig {% h %} tag in that section.

Changes to source-file links

• Provide an option to disable these links for methods/properties/etc.
• Make these links less prominent.

Add optional div tags all over the place

That way people don't have to customize the template just to get a few extra <div> tags for CSS purposes.

I could implement this by adding a new Swig tag, like so:

{% container 'class1' 'class2' %}
  <p>whatever</p>
{% endcontainer %}

And a config file like:

{ "class1": true, "class2": false }

In that case, I guess we'd create a <div> with just class1. If both were false, no <div>.

(Also: Maybe a {% span %} tag?)

Need to escape type expressions correctly

For example, it looks like we're not escaping angle brackets in type expressions at the moment.