Option to leave tag value where it is

Question

Option to leave tag value where it is

mcasimir opened this issue 11 years ago · 5 comments

Sorry for the awkward title, what i need is to create a custom tag (in this case i will call it recipe) that will be inside the description and will extract its content to doclet property without removing it.

I explain this use case by example:

/**
 * @module MyModule
 * 
 * This module has some features.
 *
 * @recipe How to use MyModule to do something.
 * ...  
 *
 * @recipe How to use MyModule to do something else.
 * ...
 */
//..

This way i could both render recipes as examples inside module docs and create a sort of global FAQ listing all recipes from all modules.

I couldn't figure out how either using defineTags options neither trying to guess position of tag reinserting it somehow into description. So I decided to ask directly here.

Em I missing something?

Answer 1 · 2015-01-09T20:19:34.000Z

By default, if you use tags that JSDoc doesn't recognize, it adds their content to a tags array on the parse result for that comment. Here's what JSDoc generates for your example (I've removed the meta property, which isn't relevant to the problem you're solving):

{
    "comment": "/**\n* @module MyModule\n*\n* This module has some features.\n*\n* @recipe How to use MyModule to do something.\n* ...\n*\n* @recipe How to use MyModule to do something else.\n* ...\n*/",
    "kind": "module",
    "name": "MyModule\n\nThis module has some features.",
    "tags": [
        {
            "originalTitle": "recipe",
            "title": "recipe",
            "text": "How to use MyModule to do something.\n...",
            "value": "How to use MyModule to do something.\n..."
        },
        {
            "originalTitle": "recipe",
            "title": "recipe",
            "text": "How to use MyModule to do something else.\n...",
            "value": "How to use MyModule to do something else.\n..."
        }
    ],
    "longname": "MyModule\n\nThis module has some features.module:"
}

Note that the name and longname properties are kind of screwed up. That's because the description needs to be at the start of the comment block. Alternatively, you can add the @desc tag before the description.

(If you have more questions about this, please send them to the jsdoc-users mailing list. The issue tracker is for bug reports and feature requests. Thanks!)

Answer 2 · 2015-01-09T20:56:03.000Z

Sorry it was not what i was asking, It was a feature request. Although I found a workaround solution that is really easy for that specific case.

I was requesting an option for defineTags to allow you to control the nesting of tags. Something like {belongsTo: 'description'}

That would have create a sort of tree of tags, not parsed in linear order but as a postvisit, so that child tags are parsed before parents.

For example the @example tag above should be a custom tag "belonging to" @description that is parsed before the description tag and optionally transformed, removed or just leaved as it is and description tag will handle it further (ie inserting it or its transformed content into 'description' property).

Right now I'm just appending the content of example into description property and adding it to a list of examples into doclet. This is just fine for me.

Answer 3 · 2015-01-12T02:57:02.000Z

Thanks for clarifying, @mcasimir. I think you could accomplish what you're trying to do by using two plugins:

A defineTags plugin, which would parse the new tag and create (let's say) a recipe array.
A newDoclet plugin, which can do anything you like with the doclet, including moving the recipe array to some other part of the doclet.

Answer 4 · 2015-01-12T13:10:35.000Z

Thank to you for your response. I'm using jsdoc to document https://github.com/mcasimir/mobile-angular-ui. I found it great for its flexibility. By I had to extend it a lot, and i felt super-uncomfortable to use it just to parse doclets, since I've to use stdout pipes and IPC to obtain doclets with jsdoc -x.

Also I encountered many inconsistencies. Now I've to finish documenting mobile-angular-ui, but I will be happy to help you, cause I will continue to use it.

I'll just report here some personal impressions, cause I know is always useful to have feedback. Sorry to not double check all issues first, feel free to throw these away if you're not interested. In case some of them interest you I can help in any way if you need.

1. Separate parsing from rendering

I think is quite common to have docs as part of a website with many other sections, and is fair that one already has its own style and rendering. Consider splitting package in 2 maybe jsdoc-parser and jsdoc (one requiring the other)

2. Provide a good parser API

Avoid forcing usage of jsdoc-conf.js and provide an easy to use parser interface. I took this from Xerces internals (I worked on it for my uni dissertation), but you may have a better one:

var jsdocParser = require('jsdoc-parser').Parser;
var parser = new jsdocParser();

parser. defineTag('mytag', function(dict){ /* ... */ });
parser.on('parserEvent', function(e){ /* ... */ });

parser.addSource('file1.js');
parser.addSource('file2.js');

var doclets = parser.parse();

3. Parser should output an object model tree with facilities to traverse/manipulate it:

This is how I made tree interface, it is a little too ssg-oriented but is just to give the idea:
https://github.com/mcasimir/mobile-angular-ui-website/blob/master/lib/Node.js

var node = root.byPath('mymodule/myfunction');
node.traverse(function previsit(doclet){}, function postvisit(doclet){});
node.descendants(filter)
node.ancestors(filter)
node.parent
node.root
// children is a wrapped collection from lodash so you can also do:
node.children.traverse(function previsit(doclet){}, function postvisit(doclet){});
node.append(child);
node.remove();

4. Handle quotes properly:

@module 'my.module'

should produce:

{ name: "my.module" }

and not

{ name: "'my.module'" }

Thus it can be used to define names with dots inside, like it is now:

@module my.module

Would result in:

{name: "module", longname: "my.module" }

That is 100% correct but sometimes, especially with events, you can have identifiers with dots.

5. Use URI scheme in place of namepaths.

They are made just to represent these kind of stuffs and have standard ways to parse, also they can be used as they are to produce dest paths:

my/namespace/myModule/~functionName
module:my/module

6. Qualify only when necessary

Outputing trees, longnames can be used just as UID/paths. In order to keep paths/namepaths compact and parsing sources in blocks we could qualify longnames only in case of name clashes. This is extremely useful to generate meaningfull and easy to read URLs:

my/namespace/myModule/~functionName
my/namespace/myModule/#functionName
my/namespace/myModule/functionName
my/namespace/myModule/module:Name
my/namespace/myModule/class:Name

Then you could provide a qualified name field with names always qualified.

7. Add `slug` or `segment` field

Add slug or segment field that is different from name but represents exactly the path segment used to create URI/longname, this is essential to remap doclets to custom path traversing tree:

{
   name: functionName,
   slug: ~functionName
}

8. Escape `/` for names using paths or '.' using namepaths:

{
  name: 'my/event',
  path: 'module/my%2Fevent'
}

{
  name: 'my.event',
  path: 'module.my%2Eevent'
}

9. Target node primarily

Not sure about this. Put rhino stuffs away in some other packages. I think (maybe i'm wrong) rhino has a smaller community and rhino stuffs make it harder to understand sources and collaborate (at least for me).

Answer 5 · 2015-01-12T15:58:42.000Z

Thanks for taking the time to provide such detailed, thoughtful feedback on JSDoc! It's always helpful to hear from real-world users.

Responses to your comments below.

1- Separate parsing from rendering
2- Provide a good parser API

Many people have asked for these changes. Unfortunately, because JSDoc was designed as a standalone CLI tool, it would take a fair amount of work to separate the parsing and rendering pieces. That work will happen someday, but not in the immediate future.

3- Parser should output an object model tree with facilities to traverse/manipulate it
5- Use URI scheme in place of namepaths.
6- Qualify only when necessary
7- Add slug or segment field
8- Escape / for names using paths or '.' using namepaths

These are all interesting ideas that I hadn't considered before. They'd all be breaking changes, but I'll keep them in mind for future versions.

4- Handle quotes properly

We keep the quotes to disambiguate things like 'my.module'.foo. If we started escaping special characters in namepath fragments, though, we could get rid of the quotes.

9- Target node primarily

JSDoc didn't run on Node.js until fairly recently, and I think there are a fair number of people who, for whatever reason, still prefer to run JSDoc on Rhino. I've isolated the Rhino stuff as well as I can, but yeah, there are places where it leaks out.