Add custom tags and properties to JSDoc XML template Haruki

[Ishita jain]

I am trying to create my own custom tags (say a tag called "ishita") to Haruki template
For that, I did the following:

1. Added following code to definitions.js in jsdoc library

    dictionary.defineTag('ishita', {

        canHaveType: true,

        onTagged: function (doclet, tag) {

            setDocletKindToTitle(doclet, tag);

            setDocletNameToValue(doclet, tag);

            if (tag.value && tag.value.type) {

                doclet.type = tag.value.type;
            }
        }
    });

2. Added following code to add a node to parent node in publish.js

    else if (element.kind === 'ishita') {
        if (!parentNode.ishita) {
            parentNode.ishita = [];
        }

        var thisishita = {
            'name': element.name,
            'description': element.description || '',
            'access': element.access || '',
         //   'virtual': !!element.virtual
        };

        parentNode.ishita.push(thisishita);

        graft(thisishita, childNodes, element.longname, element.name);
    }

3. Added @ishita tag in my source files.

By doing this I was able to create my own custom tag which is awesome.

I just wanted to know if it is correct way of doing it or not.
Because when I tried adding more custom tags such as , I was not able to..as in it was not able to recognize them..not sure why...Please let me know if this is doable or not.
Perhaps, I was doing something wrong while creating the other custom tags which i was not able to see.

Also, I am trying to add custom properties to the existing tags.

For instance, @member can have properties @name, @description and more, Now i want to add another property @observable.

In order to do that I did the following changes in publish file:

    else if (element.kind === 'member') {
        if (!parentNode.properties) {
            parentNode.properties = [];
        }
        parentNode.properties.push({
            'name': element.name,
            'access': element.access || '',
            'description': element.description || '',
            'type': element.type ? (element.type.length === 1 ? element.type[0] : element.type) : '',
            'observable': element.observable||false
        });
    }

I also added this tag in my comments of the source code.

Now, the output xml file does have this extra tag as observable but it doesnt take the value written after the tag in comments.
I am not sure what am I missing.

[Jeff Williams]

Hi Ishita,

The best way to define custom tags is to create a plugin. That way you don't have to modify the code for JSDoc itself, and your new tags will continue to work after you upgrade JSDoc. Instructions are available on the Use JSDoc website: http://usejsdoc.org/about-plugins.html

To make the @observable tag work, you'll have to define the new tag and tell it to add a property to the doclet. The plugin for that tag would look something like this (note that I haven't tested this code):

exports.defineTags = function(dictionary) {

  dictionary.defineTag('observable', { 

    onTagged: function(doclet, tag) {

      doclet.observable = true;

    }

  });

};

- Jeff

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users...@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Ishita jain]

Thanks Jeff for your help.

I did what you suggested.

My plugin has following code:

exports.defineTags = function (dictionary) {
console.log("in defineTags")   // This prints
     dictionary.defineTag('myTag', {
         onTagged: function (doclet, tag) {
            console.log("iam in myTags --- onTagged");  // this doesn't prints on console
            doclet.myTag = true;
            setDocletKindToTitle(doclet, tag);
        }
    });

};
defineTags executes but it doesnt register the tag as jsdoc doesnt read 'myTag'
I am not sure why.

[mathematical.coffee]

Just to check, you are using @myTag in your comments, right? Also, I found I had problems with tag names with capital letters in them, try a lowercs. tag name.

[Ishita jain]

Thanks!

It does fix that issue.
Now, on it executes the method ---- defineTags.

But, It still doesnt get registered as it cannot read it from my source file

exports.defineTags = function (dictionary) {

    dictionary.defineTag('mytag', {
     
        onTagged: function (doclet, tag) {
            doclet.addTag('kind', tag.title);
            console.log("inside onTagged");  // this prints

            if (tag.value && tag.value.type) {
                doclet.type = tag.value.type;
            }
        }
    });

};

In my publish file, I am using the following code:

    else if (element.kind === 'mytag') {
        console.log("found mytag"); 
        if (!parentNode.mytag) {
            parentNode.mytag = [];
        }

        var thismytag = {
            'name': element.name,
            'description': element.description || ''
        };

        parentNode.mytag.push(thismytag);

        graft(thismytag, childNodes, element.longname, element.name);
    }


But, for some reason, it never recognizes mytag
Any ideas..what am i doing wrong?

[Ishita jain]

My source javascript file has this comment in it:

                 /**
                * @mytag testmytag
                */

[Jeff Williams]

Hi Ishita,

This is probably happening because you're checking for tag.value.type, but your tag has no type.

Try tag.value.description instead.

- Jeff

--