Find a way to show namespace paths about jsdoc HOT 25 CLOSED

There has been a suggestion for a @toc (table of contents tag) in the past. This would allow you to specify exactly how you wish the reference to be listed. Like so:

/** @namespace GUI */

/** @class Windowfactory
    @memberof GUI
    @toc GUI.Windowfactory
*/

/** @namespace BrowserUtils */

/** @class Windowfactory
    @memberof BrowserUtils
    @toc BrowserUtil.Windowfactory
*/

I'm considering adding support for this.

There is already an undocumented way to achieve the same effect now by forcing the documented symbol to be considered a memberof the global scope, even though it has a dotted name. This would use the "forced membership tag" @memberof!

/** @namespace GUI */

/** @class GUI.Windowfactory
    @memberof! <global>
*/

/** @namespace BrowserUtils */

/** @class BrowserUtils.Windowfactory
    @memberof! <global>
*/

It seems like @toc would be more intuitive and flexible.

A final alternative would be to always show the full dotted names of everything in the table of contents by default, and perhaps also supply a @toc tag to allow people to override that if they wish.

from jsdoc.

ProLoser, please create a new ticket, preferably one for each specific issue you want to report, rather than adding an unrelated comment onto arcanin's ticket.

from jsdoc.

The @toc tag would be great.

Additionaly (and it's a template problem, I think), make a real tree (eventually folding/collapsing according to current namespace) would also be a nice feature. Like this :

Classes

• GUI
  • CrashReportScreen
  • FlatScreen
  • ProgressScreen
  • WebGLInfoScreen
• LIB
  • Array
  • Object

Namespaces

• GUI
  • BrowserUtils
• LIB
  • ClassUtils
  • MixinUtils

Mixins

• LIB
  • EventBehavior
  • StoreBehavior
  • VolatileBehavior
  • WidgetBehavior

from jsdoc.

Ya I'm having this problem too. For now I'm gonna switch the default template to use the longname for the text, but I may contribute by adding nesting (if this isn't a super daunting task lol). I say that because it seems like the data would have to be collected in a nested manner in order to make it easy to iterate through and display. And messing with the code that collects this data seems (from a glance) trickier than messing with how it renders.

@arcanin
For now, if you want to, you can just change line 225 of publish.js from:
if ( !seen.hasOwnProperty(m.longname) ) nav += '<li>'+linkto(m.longname, m.name)+'</li>';
to:
if ( !seen.hasOwnProperty(m.longname) ) nav += '<li>'+linkto(m.longname, m.longname)+'</li>';
and the same for the subsequent navigation populating items.

from jsdoc.

Do you have any plan for the @toc tag ? : )

Merry christmas ! ;D

from jsdoc.

I don't specifically have plans to implement a @toc tag anytime soon, but I am willing to consider pull requests :)

Michael Mathews
[email protected]

On 25 Dec 2011, at 10:48, Maël Nison wrote:

Do you have any plan for the @toc tag ? : )

---

Reply to this email directly or view it on GitHub:
https://github.com/micmath/jsdoc/issues/43#issuecomment-3270456

from jsdoc.

I would vote for the default to be full dotted names/tree view and let users override with an @toc tag or maybe just an overall flat switch

from jsdoc.

The tree view would be good, like what JSDuck does by default. The full name thing isn't so great because on any substantial project the navigation pane would have to be wide enough to show the name.

Imagine: hackabot.ajaxToolz.CSRFoMatic.fbPokemall

Navigating a tree is easier because the branches and leaves can be list items. The toc tag is a good idea too. Say there was a descriptive name given to a namespace like superNodeMasher3000Deluxe that contained various parts and pieces for the SnM-3D. With the toc tag we would be able to alias things so that they made sense in the docs and, at the same time, keep our descriptive namespaces so the code makes sense as well. I'm an abuser of autocomplete, so some of the names I use are absolutely huge. The toc tag would be awesome. :D The collapsible tree view would be amazing. :D

I volunteer to write the docs for it. :D

from jsdoc.

I'm basically with @jannon on this: Default to full dotted names/tree view, and provide an option in conf.json (maybe a boolean called templates.default.navTree?) to show a flattened list instead of a tree view. I'd prefer not to use a command-line switch, since other templates might choose not to implement this feature.

The @toc tag might be useful, but I think that could be a later enhancement.

from jsdoc.

I have implemented collapsible lists for the nav bar. I really don't know anything about web design though, so I took the code from here; it's released under creative commons so it should be OK, right? The JS file (very small, ~2KB) has the author's name up top so credit is preserved.

So currently the names show up as short names (not including namespace/whatever), and the "Classes", "Namespaces" etc title is collapsible (default they all start collapsed).

However it's not ready for pull request yet. Need to ask a few more questions.

nesting of classes

I think the whole idea of the collapsible treeview is to nest classes by their container (namespace/plugin).

How can I walk the tree of symbols in a hierarchical-fashion, so that I can generate the list structure? So top-level classes and namespaces/modules with classes should be on the first <ul>, classes in a top-level namespace/module and namespaces/modules that are nested two levels down should be in the second <ul>, and so on?

other todo before ready

• the tree should open to the page you are on (I am really over my head here - I have no experience with web design or javascript with web design).

from jsdoc.

Awesome! Thanks for taking a shot at this, @mathematicalcoffee.

Yep, we could use that code--it uses a CC license that basically puts it in the public domain. If you want to try something a bit more full-featured, jqTree is another option; the main benefit is that it remembers which parts of the tree you've expanded. We'd have to incorporate jQuery as well, but that's fine by me.

I don't think the template has access to anything like a walkable tree of namespaces. You'll have to create the tree by iterating through all the members of interest. Here's a very, very rough sketch of how you might do that:

function addLongnameToTree(tree, item) {
    /*
     * 1. check for item.longname
     * 2. if item.longname exists, split on the characters in helper.scopeToPunc
     *    (note: may want to keep the punctuation so it can be displayed in the tree)
     * 3. add each part of the longname to the tree
     */
}

var modulesTree = {};
members.modules.forEach( addLongnameToTree.bind(this, modulesTree) );
// etc.

To expand the current page on load, one approach would be to add id="current-page" to the appropriate nav entry on each output page, then add something like this (completely untested) code to the <script> tag that's near the bottom of layout.tmpl:

(function() {
    var element = document.getElementById("current-page");
    var event = document.createEvent("MouseEvents");
    event.initMouseEvent("click", false, false, window,
        0, 0, 0, 0, 0, false, false, false, false, 0, null);
    element.dispatchEvent(event);
})();

That should more or less work for the code you were looking at. If you decide to use jqTree, I'm happy to help figure out a jqTree-friendly approach.

from jsdoc.

I'm slowly getting there and now am after a bit of aesthetic advice. If you don't want to read this all, please scroll down to the collection of images in the "Various options" section and tell me which one you like the best.

In my sample document, I have the following structure:

• module: Jacket
  • class: module:Jacket~Jacket
  • namespace: module:Jacket~Pants
    • class: module:Jacket~Pants.Pants

That is, I have one module, one namespace, and two classes.

This is my current state of affairs:

I think you'll agree that the above picture is quite confusing, in particular the "Classes" section - it is not clear that the only classes in the list are the inner-most Jacket and Pants. However, it does accurately represent how the classes are nested, which can be nice (especially with a big project with many classes that can be nicely grouped by module or namespace).

How can I signal to the user which are the classes in the Classes section, or which are the namespaces in the Namespaces section, and so on?

I've experimented with a few things and present them to you here.

Various options

Terminology: a class in the classes section, or a namespace in the namespaces section, or an X in the Xes section is a "target" node (as opposed to say a namespace in the classes section which is only listed because it contains a class).

From left to right:

• the current flat index that we have in JSDoc.
• the flat index, but each section is collapsible.
• the unstyled nested collapsible index
• target nodes (bold) are styled differently to non-target ones (italic)
• only target nodes have links
• non-target nodes are marked with what type they are: brackets after the link
• non-target nodes are marked with what type they are: before the link

There is certainly some argument for the flat index being the easiest to use (though it may depend on the project - for example one I'm working on has ~20 namespaces each with 1 to 10 classes, so it would be easier to browse the classes if they were grouped by namespace allowing me to collapse the namespaces I'm not interested in).

I think you will agree that if we go with the nested structure, we must somehow distinguish target nodes from non-target ones to avoid confusion.

So, what you think would be a nice default (perhaps I should ask on the JSDoc forums too)? One thing I haven't yet played around with is displaying longnames on the sidebar, though I think these will quickly become too wide to be feasible (imagine 'module:plugins/MyModule.MyClass', and woe to you if you have more than one level of nesting..,)

@arcanis @ProLoser @micmath @jannon @matthewkastor @hegemonic

If you want to play around with this:

Check out the 'template-improve-sidebar' branch in my fork.

Have a look at templates/default/publish.js, function buildNav and the _helper function defined in there: https://github.com/mathematicalcoffee/jsdoc/blob/template-improve-sidebar/templates/default/publish.js#L150.

node.label is what will be displayed inside the <li></li> for that node (it may include HTML, which will be interpreted). isTarget will tell you whether the current node is a target node or not.

from jsdoc.

(Note - I've broken other stuff in the default template so for the moment only the index.html page will be generated).

from jsdoc.

When you say collapse, I assume you talk about the regular collapse behavior of a single node, right ?

Maybe it would be nice to see only the 1-level elements when the section is collapsed, and every element when it is expanded (current behavior). With maybe a bonus point for storing the state in a cookie for future page loading :)

If you don't see what I mean I can try to make a prototype, but I don't really have the time atm

from jsdoc.

Also, another way to prevent confusion when reading the doc would be to use different icons in the tree for classes / namespaces / modules

from jsdoc.

I think it would be best to omit the "Classes"/"Modules"/"Namespaces" headings when we're displaying the symbols in a tree view. Otherwise, as @mathematicalcoffee points out, the navigation tree becomes very confusing. Instead, we can simply interleave the symbols based on their namepaths, and provide visual guidance about which type of symbol we're showing at each level.

I played around with different ways to display the following list of symbols:

module:foo
module:foo~ClassA
module:foo~ClassB
module:foo/bar
module:foo/bar~ClassC
module:foo/bar~ClassC.NamespaceOne
module:baz
module:baz~NamespaceTwo
module:baz~NamespaceTwo.NamespaceThree

Here's one example showing how we could display these symbols in a tree (excluding the "module:" prefixes):

And another example that includes the full namepaths (again, excluding the "module:" prefixes):

I'm not wedded to these examples by any means, but I think there are a few things they do well:

• Navigating the tree is reasonably intuitive.
• You get two sources of information about the types of symbols that are being displayed: the "M"/"C"/"N" boxes (for novices), and the "/"/"~"/"." symbols (for JSDoc pros). (You could even make the "M"/"C"/"N" boxes display a "Module," "Class," or "Namespace" tooltip on hover.)
• Second example only: At any point in the tree, it's easy to see the full namepath (at the expense of a considerably wider navbar).

The examples don't show disclosure arrows for each item, but perhaps we don't need them...

I'm curious to hear what people think of these mockups. You can mess around with them further at this JSFiddle if you're interested.

from jsdoc.

I thought I would dislike this approach but actually, seeing the mock-up, I find I actually like it quite a lot. My only concern is that, for trees with a very deep amount of nesting, horizontal realestate becomes a problem (as each branch gets more and more indented). This is especially true with longer names thrown in. With a simple list you could resort to horizontal scrolling but that would be confusing with a tree, wouldn't it?

from jsdoc.

As one with a very large project with many modules (100+) where the module name/path is quite long, I had to implement a tree view or else the long list was just ridiculously unusable.

So I like this very much, especially variant 1. It could be a setting to display full name in tree view, but it wouldn't work for us.

One suggestion with the collapse expand icons, is to do it like the Spotify desktop app does it. On hover on the whole tree view, you exchange the module/ns/class icons with the arrows. I find it to be a good solution in Spotify.

Another note is that is the character indicators (~, ., /) really needed? The icons is good enough I think.

The next step for us in our project is to add a search box in the top that filters the tree view (without removing the structure) according to the search criteria.

from jsdoc.

@tregusti, the character indicators (~, ., /) would be useful to communicate the kind of membership relationship between a member symbol and its container; is this a static member, an instance member or an inner member, for example. Whether that information is important/useful enough to clutter up the display is up for debate of course.

from jsdoc.

For the reasons @micmath and @tregusti point out, the version with the full namepaths is a nonstarter for most projects. It's fine with me if we omit the leading portion of the namepath, as well as the leading characters (~, ., /, #).

@mathematicalcoffee, any thoughts on this, and is this something you feel like you could tackle? I'd be happy to lend a hand if you like, although I'm pretty swamped for the next week or so.

from jsdoc.

I do very much like the combined view (I'm personally not a fan of the preceding ''/'#'/etc but see how this can be useful) - I can always add some configuration so the user can specify if they want to show the full paths (foo/barClassC.Namespace1) or the preceding symbol (.Namespace1) or just the name (Namespace1).

It is quite a bit different from the current default template for JSDoc 3 though - should this be separated into a different template to the default then or should it be combined? What if users go "hey, I liked the flat list"? I could add a toggle to switch between a flat and nested view, I guess.

Also, it would be nice to be able to filter what is shown if the sidebar is to be combined. E.g. I might only want to see Classes, or just Namespaces. I guess some checkboxes could be added to this effect --> the user can select to show classes and/or namespace and/or modules and/or ...

So:

• add a configuration option: flat vs nested view
• add a configuration option: show full path (foo/bar~ClassC.Namespace1) or just the name (Namespace1) or the preceding punctuation too (.Namespace1)
• (wishlist): checkboxes for the user to filter what shows in the list - classes, namespaces, events, modules (replacing the previous sidebar where you had a heading for each category).
• (wishlist): add a search box which filters showing matching symbols?

I think I can slowly work on this. Looking good!

from jsdoc.

@mathematicalcoffee: Good point that the tree view is very different from the current default template. For now, we should probably change the typeface and color scheme to fit more gracefully into the existing template. (I had hoped to spruce up the default template for 3.2, but it seems unlikely that I'll have time.)

Regarding the list you provided:

• add a configuration option: flat vs nested view

I agree that this is needed.

• add a configuration option: show full path (foo/bar~ClassC.Namespace1) or just the name (Namespace1) or the preceding punctuation too (.Namespace1)

I suggest outputting the full path/name/punctuation by default, but using CSS classes to hide the full path and punctuation. That would provide more flexibility; for example, if you wanted, you could add a toggle that shows and hides this information after the docs have been generated.

• (wishlist): checkboxes for the user to filter what shows in the list - classes, namespaces, events, modules (replacing the previous sidebar where you had a heading for each category).
• (wishlist): add a search box which filters showing matching symbols?

Excellent suggestions, but no need to tackle them as part of this issue.

from jsdoc.

At this point, I'm not inclined to change the sidebar (or much of anything else) in the default template. The Baseline template, which will eventually become the new default template, uses a tree view in the sidebar. That template is still a work in progress, though.

In the short term, JSDoc now provides a method that converts a list of longnames to a tree structure, which should make it much easier for users to build their own tree view for the navbar. (Baseline already uses this method to generate its tree view.) However, the new method isn't documented at all right now, which means it's not so useful for people who are not me.

I'll keep this issue open until I've documented the longname-to-tree method.

from jsdoc.

Hi @hegemonic, we also want a tree to use in our template :)
About the longname-to-tree method, could you give some more hints or pointers in regards to this yet-to-be documented method?

from jsdoc.

The longnamesToTree method is now documented on GitHub master. It's available as both module:jsdoc/name.longnamesToTree and module:jsdoc/util/templateHelper.longnamesToTree.

from jsdoc.