Configurable way to define default values for tags

[GoogleCodeExporter]

I want to guarantee a certain quality level to the documentation of our new
project (CKEditor). For that I want to have the following things in the
documentation:

- To guarantee that everything is document, not documented stuff must have
a well visible red warning.

- All documented things must have an @example tag.

- The @since value must always be available.

To do that I'm currently applying some "hacks" to the 2.0 code:

---

this.comment = comment || new JSDOC.DocComment("/** <span
style=\"color:red\">&lt; NO DOCUMENTATION AVAILABLE &gt;</span> */");

---

// @example
var examples = this.comment.getTag("example");
if (examples.length) {
    this.example = examples.map(
        // trim trailing whitespace
        function($) {
            $.desc = $.desc.replace(/\s+$/, "");
            return $;
            }
        );
}
else {
    this.example = '<span style="color:red">&lt; NO EXAMPLE AVAILABLE
&gt;</span>';
}

---

// @since
var sinces = this.comment.getTag("since");
if (sinces.length) {
    this.since = sinces.map(function($){return $.desc;}).join(", ");
}
else {
    this.since = '3.0';
}

---

As said, the above are hacks to the original code. It would be much better
if there would be some way to configure it in the command line call. We
could have things like the following:

-def="<span style=\"color:red\">&lt; NO DOCUMENTATION AVAILABLE &gt;</span>"

-def@example="<span style=\"color:red\">&lt; NO EXAMPLE AVAILABLE &gt;</span>"

-def@since=3.0

Of course, any other syntax would be ok for that. This feature would
strongly help us guaranteeing our documentation quality.

Original issue reported on code.google.com by fre...@gmail.com on 7 Jun 2008 at 4:55

[GoogleCodeExporter]

I think you should be trying to use the template more for this type of 
customization. I've tried hard to make 
that possible by designing JsDoc Toolkit as I have (though perhaps I need to 
document these techniques 
better).

For example use the -D commandline option to define a "since" option like so:

-D="since:3.0"

Then in your template you can overlay that -D value onto the member's "since" 
property like so:

{! member.since = member.since || JSDOC.opt.D.since !}

Another option is to use the JsPlate logical controls, like so:

<if test="member.example.length">
  <for each="example" in="member.example">
    <pre class="code">{+example+}</pre>
  </for>
<else />
  <span style="color:red">< NO EXAMPLE AVAILABLE ></span>
</if>

I would strongly encourage you to modify your template before trying to hack a 
solution into the core code, 
especially for items like this that are concerned with the "view" aspect of 
your documentation.

I'm marking this issue as invalid but If you've tried what I suggest and still 
feel you absolutely need to change 
the core code please resubmit this issue and explain why. Also feel free to ask 
for advice on customizing 
templates on the user list.

Original comment by micmath on 7 Jun 2008 at 6:36

• Changed state: Invalid

[GoogleCodeExporter]

A powerful template system is a nice thing to have, and I'm ok to put all my
customizations on it. We'll much probably have our custom template in the 
future.

The ticket instead makes reference to a generic feature, that can definitely be 
used
by others. The basic idea is not having to touch the templates to do some 
stuff, or
even changing templates with easy, and still have the same results.

Note that the proposal is not talking about formatting and styling, which is
definitely a template thing, but to data manipulation. It is quite a flexible 
feature.

I still think this is a nice thing to have, but I can definitely live without 
it if
others don't see any value on having it.

Original comment by fre...@gmail.com on 7 Jun 2008 at 9:54

[GoogleCodeExporter]

If you mean that there should be a way to use a given default value whenever a 
particular tag was missing, I'd 
guess this would be of very limited value to most people but I might be wrong. 
Its an enhancement that I 
personally wouldn't give a high priority to but maybe you should propose it to 
the user group and see what sort 
of response you get.

I'd consider accepting a patch if anyone wants to write one using the -D option 
somehow.

Original comment by micmath on 7 Jun 2008 at 10:29

[GoogleCodeExporter]

Here you have a proposal patch for it.

- I found that using -D for it would not be a good idea. I would still want to 
define
a variable named "author", but not define the default value for @author.

- I'm introducing the -I option for that. The "-d" option (for "default") would 
be
better, but it is already used. I couldn't think about anything better than -I, 
for
"initialize". Anyway, any other letter would be ok.

- It accepts an special case: "$:value", to define the default value for 
undocumented
symbols.

This is just a proposal, and so of course can be adapted. Please take in
consideration that I have just a couple of days experience with to JsDoc Toolkit
source code ;)

Original comment by fre...@gmail.com on 8 Jun 2008 at 11:13

Attachments:

• 155.patch