Re: [Jsdoc-user] custom tags and creating a default view

[Gabriel R. <gab...@gm...>]

Hi Kate,

> 1)       What are the steps for creating a custom JSDoc tag? I want an
> @Example tag where I can provide 2 or 3 lines of code to show how an
> object/function/etc can be implemented. I may be able to figure out
> which tmpl (or other) file I should go into to create the tag, but I'm a
> little pressed for time on my project, so I first thought I'd see if
> anyone already has some steps for how to create a tag.

The support for custom tags in JSDoc is based on being able to write a
very small bit of Perl code. You can define custom tags in the
.jsdoc_config file. For the example you're describing, a start would be
to add something like this to .jsdoc_config

   $METHOD_ATTRS_MAP{example} =
        sub {
            my $ex = $_[0][0];
            return "<div style='background: #CCCCCC; border: dashed 2px; padding: 12px; width: 70%'> <code>$ex</code></div>";
        };

This would put all text given as an @example in a shaded and bordered
block in the HTML. 

One of the downsides of this approach is that you can't control where
the block will be displayed; it will simply be together with the other
tag output (like @return and @param). 

Also, newlines and whitespace formatting are stripped from tag input
like this, which is probably not really what you want...


> 
> 2)       Is there a way to set how JSDoc opens when people click the
> index.html file? Ideally I would like them have the index.html file open
> with the "Overview" material provided at the top. As it is now, if you
> click index.html, you then have to click the link at the top called
> "Overview" to get the look that I would like to present people upon
> first opening the file. Is there a way to do this? 

The behaviour of JSDoc is:
    - If there is an overview page supplied, and more than one
      JavaScript file is being processed, the opening page will be the
      Overview page.

    - Otherwise, the first class page is displayed.


Hope this is of some help.


Regards,

    Gabriel