On Fri, Jun 7, 2013 at 3:15 PM, Nick Wellnhofer <[email protected]> wrote: > It does make sense. But from a practical point of view, most host languages > will use 'new' as constructor. So it would simplify things if we moved the > constructor's documentation to the 'new' function and use an alias only for > languages that have constructors with different names.
There are some practical problems with the approach of moving the constructor documentation from `init` to `new`. First, abstract classes, e.g. Lucy::Search::Query, don't *have* `new` -- they only have `init`. We could add a `new` function to such abstract classes, but calling it would just result in an unavoidable runtime exception. I question whether it's for the best to increase library size and create "attractive nuisance" functions which trick people into writing code that compiles but inevitably crashes out, solely because we need something to attach our documentation to. (I know that's not your intent, either -- it's just a side effect of the proposal.) Second, Clownfish doesn't currently enforce the relationship between `new` and `init`, so it's possible that the documentation may not be sync'd. The Perl bindings will provide a constructor called `new` -- because naming constructors `new` is idiomatic for Perl -- but when you call Foo->new from Perl, behind the scenes Foo_init() will be invoked, *not* Foo_new(). The same will be true for Ruby and Python -- because Foo_new() does not support subclassing, while Foo_init() does. (Incidentally, Python constructors don't use `new`, they use the class object as a function: `x = MyClass()` -- see <http://docs.python.org/3/tutorial/classes.html#class-objects>.) If other folks are not satisfied with having docs attached to `init`, but I'm not satisfied with having them attached to `new`, can we please keep trying to find consensus for a little while longer? > I think it would also be more consistent for classes with multiple > constructors. In this case, we have to document the additional constructors > because there aren't corresponding 'init' functions. At the core level, Clownfish doesn't currently differentiate between inert functions, whether they're named `new`, `init`, `decode_utf8_char`, `freeze`, or whatever. (The Perl level treats `init` specially, though.) I think it makes sense to make `init` special -- like constructors in C++ or Java, like `initialize` in Ruby and like `__init__` in Python. Maybe we should be trying to figure out some syntax, keyword, or capitalization scheme to make *multiple* constructors special? (They achieve that in Java etc. by using the class name in conjunction with signature overloading.) > But it's no problem to work with the current system. I can simply copy the > 'init' documentation if 'new' doesn't have one. I'm not enthusiastic about making exact duplicates of the documentation for every constructor, though. :( That's the kind of ugliness they have to accept in Java because of signature overloading, but it would be nice if we could avoid it. Marvin Humphrey
