Opened 13 years ago

Closed 12 years ago

#1471 closed enhancement (wontfix)

API doc generator -- recognize literal return values

Reported by: skinner Owned by: Neil Roberts
Priority: lowest Milestone: 1.0
Component: Doc parser Version: 0.4.1
Keywords: Cc: skinner@…
Blocked By: Blocking:

Description

The automatic generation of API documentation is a great thing:

http://dojotoolkit.org/api/

It would be cool if the doc parser automatically recognized literal return values, so the developer doesn't have to explicitly declare a return type if the return value is a literal.

So, instead of having to do this:

dojo.foo.bar = function() {
   if (...) {
      ...
      return true; // boolean
   }
   return false; // boolean
}
dojo.foo.getDayName = function() {
   switch (day) {
      case 1: 
        return "Monday"; // string
        break;
      case 2: 
        return "Tuesday"; // string
        break;
   }
}

You could instead just do this:

dojo.foo.bar = function() {
   if (...) {
      ...
      return true;
   }
   return false;
}
dojo.foo.getDayName = function() {
   switch (day) {
      case 1: 
        return "Monday";
        break;
      case 2: 
        return "Tuesday";
        break;
   }
}

Change History (12)

comment:1 Changed 13 years ago by skinner

Type: defectenhancement

comment:2 Changed 13 years ago by dylan

Milestone: 0.5

comment:3 Changed 13 years ago by bill

Owner: changed from neil to Neil Roberts

comment:4 Changed 13 years ago by Neil Roberts

Resolution: invalid
Status: newclosed
The main problem here is that not every return value is intended to be used. The reason they're documented the way they are serves this purpose. Even then, it's impossible to predict a return value of, say, "string"
true

This is why it's up to the user to tell us what it's returning. It seems crummy, true, but that's the tradeoff for a dynamic, mutable, programming language

comment:5 Changed 13 years ago by skinner

Hi pottedmeat,

Thanks for adding that last comment, with the explanation for closing the ticket, but I'm having trouble understanding the explanation. You say that "not every return value is intended to be used", but I don't get that. If there's a literal return value actually in the code, then isn't that return value already actually in use?

If you have a line of code that says

return true;

then isn't it safe to add "boolean" to the list of return types for that function? Or is there something I'm not getting? Maybe you could point me to an example of some code where, as you say, "it's impossible to predict a return value" of a literal?

comment:6 Changed 12 years ago by skinner

Resolution: invalid
Status: closedreopened
Version: 0.30.4.1

comment:7 Changed 12 years ago by Neil Roberts

So let's say you have a function that returns some value, but you can pass a flag that tells the function to instead return a boolean that tells us something about that value. If we're parsing automatically, what is the correct return value? That value, or the boolean?

That's what I mean that it's impossible to predict a return value. The best the parser can return in this case is "mixed", even though we probably want it to show "String" for the return value. I'd still like to close this ticket, I don't see a good way we can provide an intelligent default.

comment:8 Changed 12 years ago by skinner

Thanks for the reply, but I guess I still don't understand. In the scenario you just described, it sounds like the function returns either a string value or a boolean, in which case the return type *should* in fact be "mixed" (or perhaps more descriptively, "mixed: String or Boolean"). If the function sometimes returns a boolean, then why would you ever want the doc parser to ignore the fact that the function returns a boolean? Could you point me to some example in the dojo code base where this comes up? Or even just some made-up example code might help me understand.

comment:9 Changed 12 years ago by Neil Roberts

Because we don't want to sacrifice clarity for the majority by providing them information that only applies to the minority. I don't want the parser to ignore anything, I want the parser to be dumb when it comes to situations like this.

My point is that in order for this to be useful, we have to make a number of assumptions that JavaScript does not allow us to make:

  • We have to assume that just because a return value is there, it's frequently returned (if it's returned at all), and that someone looking at docs for the first time will want to see it.
  • (tied to the above point) We have to assume that doing this won't result in occasional, or even frequent information overload.
  • We have to assume that the presence of a return value means that it's returned, even though the function might typically return "undefined" by reaching the end of the function.
  • If we can figure out one literal value, but there's a return of another value not documented, we're left with "mixed: boolean and ???"

Here's a little example:

  function(){
    if(false){
      return true;
    }
  }

Sure, it's a bad example, but my point is that the parser will now understand "returns: boolean".

  function count(list, /*int?*/ hasCount){
    // summary: Returns the size of the array.
    if(arguments.length > 1){
      if(list.length == hasCount){
        return true;
      }
    }else{
      return list.length;
    }
  }

This is what I was hinting at earlier. Who is to say that I intended for this function to be used with the optional second parameter? As the author of this function, I want to be able to say "This tells you how many items in an array", and then add a little aside: "Oh, but I added comparison for this one guy who had a weird use case where he needed it." The parser cannot figure this out, and JavaScript, by default, allows us to do dumb stuff like put a return in an if(false) block.

comment:10 Changed 12 years ago by skinner

Thanks for the examples. Much appreciated. I understand better now where you're coming from. I still think it would be a fine thing for the generated documentation to completely and accurately reflect the actual return types used in the code, but I can understand how this is a debatable issue. Thanks for all the work on the doc parser.

comment:11 Changed 12 years ago by Adam Peller

sounds like a wontfix, but certainly no intention of fixing in 1.0?

comment:12 Changed 12 years ago by Neil Roberts

Resolution: wontfix
Status: reopenedclosed
Note: See TracTickets for help on using tickets.