On Tue, Jun 4, 2013 at 7:10 AM, Nick Wellnhofer <[email protected]> wrote:
> Another thing I noticed is that the DocuComments for the Perl constructors
> are taken from the 'init' functions, not the 'new' functions. What's the
> rationale behind this?
Our Perl constructors, which are named `new` by default, actually wrap `init`
rather than `new`.
The `init` functions allows us to supply objects blessed into arbitrary
classes at runtime. In contrast, the vast majority of `new` functions defined
in core C code are convenience wrappers which allocate a blank object and then
immediately invoke `init` with the arguments which were passed in. They are
shorter, but less flexible.
// Equivalent:
Hash *hash = Hash_init((Hash*)VTable_Make_Obj(HASH), 0);
Hash *hash = Hash_new(0);
Other languages have special initialization constructors with essentially the
same behavior as our `init`: Ruby's `initialize`, Python's `__init__`, etc.
http://ruby.about.com/od/oo/ss/Instantiation-And-The-Initialize-Method.htm
http://docs.python.org/3/reference/datamodel.html?highlight=__init__#object.__init__
> For the C library, we have to document primarily the
> 'new' functions. I could add a special case to the code that generates the C
> documentation, but it would make more sense to me to move the DocuComments
> from 'init' to 'new'.
Now that you've brought this up and forced me to think it through... Perhaps
we should consider instead formalizing our commitment to `init` and keeping
the docs there. In addition, maybe we should start autogenerating `new`
implicitly, allowing us to delete a few lines each across a broad number of
files.
There are a few odd cases which make the situation a little more complicated:
* Abstract classes define `init` but not `new`. (At the C level, at least.
The Perl bindings are different.)
* Some classes have no constructors: BoolNum, HashTombstone.
* Some classes need many custom constructors: CharBuf, Err.
* Several classes present constructors (named "open" by convention) which
attempt to return NULL and set an error variable on failure rather than
throw exceptions.
However, I don't think those oddities spoil the rationale.
Does that make sense?
Marvin Humphrey
