incubator-lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <>
Subject Re: ProximityQuery
Date Sat, 20 Mar 2010 19:09:19 GMT
On Fri, Mar 19, 2010 at 10:08:21PM -0500, Peter Karman wrote:
> Aesthetic comment: I like C++ style comments for legibility and
> speed-of-writing.

Agreed, they are definitely superior for line comments.

> The longer block of comments around PhraseScorer_calc_phrase_freq is
> helpful.  The concept of "phrase frequency" had not scored well on my
> grok-o-meter.

Calc_Phrase_Freq() is documented in PhraseScorer.bp.  I thought about adding
additional explanatory comments to PhraseScorer.c, but I think that might be
overkill.  If you had seen this, would it have been enough?

    /** Calculate how often the phrase occurs in the current document.
    Calc_Phrase_Freq(PhraseScorer *self);

> The capitalization of function names confuses me (not specific to this
> revision). I see PhraseScorer_Calc_Phrase_Freq and
> PhraseScorer_calc_phrase_freq. I know intuitively that somehow that
> convention must be internally consistent with the magic of Clownfish, etc.,
> so I'm guessing I just haven't yet come across where the difference in case
> is documented.

OK, this was good to know.  The capitalization distinction is actually very
important, and the fact that you're this deeply involved and weren't 100%
clear means that we definitely need to take action to improve the situation. 

Rather than explain things in an email reply here (which fresh Lucy hackers
wouldn't see), I've written up a proposed Lucy::Docs::DevGuide starter.  It's
below my sig.

> All those GOTO calls are indeed "non-standard form" (wink wink, nudge nudge)
> and were what sparked my initial question to the list.

I thought about commenting that section, but I couldn't really improve on
Nate's code.  It's self-documenting and impressively compact.  The larger
algorithm is described in the multi-line comment above.  So maybe leave it as
is for now?

Marvin Humphrey

parcel Lucy;

/** Quick-start guide to hacking on Lucy.
 * The Lucy code base is organized into roughly four layers:
 *    * Charmonizer - compiler and OS configuration probing.
 *    * Clownfish - header files.
 *    * C - implementation files.
 *    * Host - binding language.
 * Charmonizer is a configuration prober which writes a single header file,
 * "charmony.h", describing the build environment and facilitating
 * cross-platform development.  It's similar to Autoconf or Metaconfig, but
 * written in pure C.
 * The ".cfh" (or historically, ".bp") files within the Lucy core are
 * Clownfish header files.  Clownfish is a purpose-built, declaration-only
 * language which superimposes a single-inheritance object model on top of C
 * which is specifically designed to co-exist happily with variety of "host"
 * languages and to allow limited run-time dynamic subclassing.  For more
 * information see the Clownfish docs, but if there's one thing you should
 * know about Clownfish OO before you start hacking, it's that method calls
 * are differentiated from functions by capitalization:
 *     Indexer_Add_Doc   <-- Method, typically uses dynamic dispatch.
 *     Indexer_add_doc   <-- Function, always a direct invocation.
 * The C files within the Lucy core are where most of Lucy's low-level
 * functionality lies.  They implement the interface defined by the Clownfish
 * header files.
 * The C core is intentionally left incomplete, however; to be usable, it must
 * be bound to a "host" language.  (In this context, even C is considered a
 * "host" which must implement the missing pieces and be "bound" to the core.)
 * Some of the binding code is autogenerated by Clownfish on a spec customized
 * for each language.  Other pieces are hand-coded in either C (using the
 * host's C API) or the host language itself.

inert class Lucy::Docs::DevGuide { }

View raw message