ID:44087
 
Keywords: design, programming
Last night, I was browsing around ThinkGeek for all of the gadgets, and I started transcribing one or two down something like this:

Photographic Eyewear:
        A "pair of glasses" which can take a picture of what is currently being
        seen by the user when triggered, using a small camera embedded in the
        bridge.  No internal memory, must be connected to an external permanent
        memory by wire lead or a wireless network.

        Parts:

        (Frame)
        + Micro Photo Camera
        / Trigger Mechanism
                | Audio/Verbal Trigger
                | Button Trigger
                | Expression Trigger
                | Neural Trigger
                | Wire Input
                | Wireless Receiver
        / Output Link
                | Wire Output
                | Wireless Transmitter
        / Power Source
                | Electrical Input
                | Micro Power Cell
        * Eyeglass Lenses

        The lenses are optional; they can be any make of eyeglass lens, such as
        those curing myopia or hyperopia or those obscuring harmful ultraviolet
        radiation, or may simply be left out to allow the device to act as a
        portable and convenient camera only.

        As with optional parts in any other item, lenses are not included by
        default.  A purchaser of photographic eyewear should contact an
        ophthamologist for manufacturing a proper set of lenses.

        The device has no processor and thus cannot be used as smartglasses.

        Specific behaviour is as follows:

        ==Audio/Verbal trigger==

                Device takes and transmits a photo whenever it hears a certain
                noise.  Most users program it to the sound of a code word or a
                simple physical noise like a cluck or a snap of the fingers.

        ==Button Trigger==

                Device takes and transmits a photo whenever a small button on
                the frame is pressed.  This allows silent photo-taking, but
                requires a free hand.

        ==Neural Trigger==

                Device takes and transmits a photo whenever the user
                concentrates on the activity.  This is silent and does not
                require hands free, but requires practice and can result in
                missed photographs or accidental photographs.

        ==Expression Trigger==

                Device takes and transmits a photo whenever the user makes a
                certain expression for a certain amount of time.  The device
                uses small lasers to detect the contortions of the face.
                Typical gesture is a three-second wink, as if scrutinising an
                object.

        ==Wireless Trigger==

                Device takes and transmits a photo whenever the device receives
                a certain signal.  Continuous receipt of the signal will cause
                the device to repeatedly take photographs after a short delay
                each time.

        ==Wire Trigger==

                Device takes and transmits a photo whenever the device receives
                a pulse along an electronic circuit.  Continuous flow of the
                circuit will cause the device to repeatedly take photographs
                after a short delay each time.

                Usually the wire trigger is fed by a handheld button or switch.


I looked at it and looked at it and looked at it and thought, "Wow, that's actually a really good documentation format."

Then I got stupid:

/*
Name of the item or part:
        If a line includes no leading formatting, it is descriptive only.
                   Leading whitespace is ignored, but it is recommended to
                        make the format human-readable.

        If a description line ends in a period, the next line is considered
        part of the same paragraph and is led with a double-space.
        I always thought it was lazy how W3C recommends trimming everything
        to a single-space when it is improper grammar and improper typography
        to do so.

        A list of parts is handled with a certain syntax by using a special
        markup.  Whitespace leading up to the symbol and after the symbol is
        ignored.

        (Integral part, for display/repair purposes only)
        #Not interchangeable with other parts
        + Part that must be included for item to work (included by default)
        * Part that may optionally be included (not included by default)
        / Sub-inventory and is not an actual part itself
                | One of the possible parts that must be selected from
                | Second possible part that must be selected from
                | ...
                | Last possible part that must be selected from
                //Sub-Subinventory
                        || One of the possible parts in the sub-subinventory
                        || ...
                        || Last possible part in the sub-subinventory
                //Second sub-subinventory
                        ++ Mandatory part in the sub-subinventory
                        ** Optional part in the sub-subinventory
        * Another optional part at normal depth

        #It is not mandatory to list parts in a single block -- they should be
        # compiled from the whole item -- but it is strongly recommended to
        # ensure ease of readability.

        Each part in the item is created when the item is parsed, unless a
        part by that name already exists.  Parts of the same name are thus
        interchangeable between all items that use them.

        Parts cannot be installed or uninstalled while the item is being used
        or worn.  The item must be removed from the body and handled at a work
        bench (usually in a Machine Shop).

        All descriptions are compiled
        into a single string.  Two or
        more line breaks are considered
        syntax, but line breaks are not
        and are considered part of the
        same paragraph.

        #Lines prefixed with a pound are comments and are ignored.

        Items are normally handheld.  If they can be worn, they use a certain
        syntax to indicate all of the locations they may be worn in.  Each
        line of the syntax indicates one possible wear position, and each
        location in the syntax indicates the body parts that are covered by
        the object.

        #This example would say "Wear on Face" as a possible action for the
        # object, handled by the game engine.

        #Syntax:
        #Opening brace
        #Name displayed to player, followed by a colon
        #One or more of:
        # One of 'covers', 'layers', 'touches', followed by a hyphen, followed
        #  by a comma-separated list of location names.
        # A semi-colon is necessary unless the next symbol is a closing brace
        #Closing brace

        #Internal whitespace and linebreaks are ignored, but the first line
        # ignoring leading whitespace must start with a brace.

        #Example:
        {Face: covers - human eyes; touches - human nose, human left ear,
        human right ear}

        #covers - list of locations that the object is worn on top of
        # (cannot have anything else over top)

        #layers - list of locations that the object is worn on top of
        # (but can still have something else over top)

        #touches - list of locations that the object rests against
        # (but cannot be equipped there if something is covering them or if
        #  too many layers are used)

        Special features are built-in symbols that determine what the object
        can do.  Special features are part of the game engine, and the parsing
        of each special feature line should also be handled by the game engine
        to determine what special properties the object should have.

        %Powersource
        %ElectricalAttachment(powersource, poweroutput)

        Scripts are the meat and potatoes of the item and are used to handle
        how the object behaves.


        ~Script label
        #Script labels can be called from the script as functions, or called by
        # the engine if they use certain hard-coded names.
        :line of script
        :line of script
        :line of script

        #A line beginning with a $ is a "verb" of this item that the player can
        # activate.
        $action
        :line of script
        :line of script
        #Lines prefixed with pound in the script are comments.
        #Lines of script must always be prefixed with colons.

        #Whitespace in a script is ignored.
        :#Lines prefixed with both a colon and a pound are also comments.

        #This is still considered part of the user-action, regardless of
        # intervening whitespace or comments!
        :lval = rval
        :condition {
        :       line of script
        :       line of script
        :       condition { #Inline comment
        :               nested line of script
        :               nested line of script
        :               #Infinite nesting should be fine.
        :       }

        Disabling an item in this file is done by surrounding the item with
        multiline Slash-Star and Star-Slash C-style comments.  Do not be
        tempted to use the C++-style Slash-Slash comments, as this indicates
        a sub-subdirectory.
*/


A self-documenting object definition language.

Estimated time to release: 14 years (assuming no setbacks)
Well, you wouldn't want to underdesign anything, would you?
[EDIT] One point I'd like to make - if you're using the hash symbol rather than double-slashing, it'd make more sense to me to also change the block comments specifier to #* or something to aid consistancy.