namespace eval $NS {}

oo::class create ${NS}::Wrapper {
    constructor {path} {
        # Wraps a shared library / DLL, loading it in the process.
        #   path - path to the shared library.
        #
        # It is strongly recommended that the path to the shared library be
        # specified as an absolute path. Otherwise, it is located in a
        # system-specific manner involving operating system version, environment
        # variables, registry settings (on Windows), phase of the moon etc..
        # This is not advisable for both reliability and security reasons.
        #
        # When no longer needed, the object can be deleted in the usual manner
        # (via `rename` to an empty string) or by invoking its `destroy` method.
        #
        # Returns the name of the created object.
    }
    destructor {
        # Destroys the object and releases internal resources.
        #
        # The managed library may be unloaded if there is nothing else
        # holding a reference to it.
    }
    method path {} {
        # Returns the file system path for the wrapped library or image wrapped
        # by the object.
        #
        # The returned path may be or may not be normalized and may be
        # in native form or Tcl's canonical form. If no `path` argument
        # was provided to the constructor, an empty string may be returned
        # on some platforms.
    }
    method addressof {symbol} {
        # Returns the address of a symbol from the loaded library.
        #   symbol - name of the symbol
        # The command will raise an error if the symbol is not found.
    }
    method function {fnname fntype parameters} {
        # Creates a Tcl command to invoke a C function in the loaded library.
        #  fnname - name of the function and optionally, Tcl command
        #  fntype - The type definition for the return value from the function
        #  parameters - List of alternating parameter name and type definitions
        #
        # The command creates a Tcl command corresponding to a C function
        # contained in the library. The function must be one that follows the
        # default C calling convention (See [Calling conventions]).
        #
        # The $fnname argument is a one or two element list, the first being the
        # name of the C function and the second, if present, being the name of
        # the corresponding Tcl command. The latter defaults to the former if
        # unspecified. Unless fully qualified, the command is created in the
        # namespace from which it is called.
        #
        # The return type of the C function is specified through the $fntype
        # argument which should be a [type declaration][::Concepts::Return types].
        # See [syntax][::Cookbook::Return type declaration].
        #
        # The $parameters argument is a list of alternating parameter names and
        # type declarations that describe the
        # [parameters][::Concepts::Parameters] of the C function. The parameter
        # name is only used to construct error messages while the latter
        # determines how arguments are converted and passed to the C function.
        # See [syntax][::Cookbook::Parameter declaration].
        #
        # The return type as well as parameter type declarations may have
        # annotations that control semantics and behavior with respect to
        # how values are passed and converted between Tcl and C. See
        # [Functions][::Concepts::Functions] for details of these.
        #
        # The command will raise an error if the function identified by
        # $cname is not found in the loaded DLL.
        #
        # Returns the name of the created Tcl command.
    }
    method stdcall {fnname fntype parameters} {
        # Creates a Tcl command to invoke a C function that uses the
        # `__stdcall` calling convention from the loaded library..
        #  fnname - name of the function and optionally, Tcl command
        #  fntype - The type definition for the return value from the function
        #  parameters - List of alternating parameter name and type definitions
        #
        # The command creates a Tcl command corresponding to a C function
        # contained in the library. The function must be one that follows the
        # `__stdcall` calling convention (See [Calling conventions]). The only
        # platform where this differs from the C calling convention is
        # 32-bit Windows. On other platforms, this method is a synonym for
        # [function].
        #
        # See [function] for other details.
        #
        # Returns the name of the created Tcl command.
    }
    method functions {fnlist args} {
        # Creates Tcl commands for multiple C functions within the loaded library.
        #  fnlist - list of function definitions
        #  -ignoremissing - do not raise an error if a function is not found
        # This is a wrapper around the [function] method that provides some
        # syntactic sugar for defining multiple functions. The $fnlist
        # argument is a flat (not nested) list of function name, return type and
        # parameter list in the same form as described for the [function]
        # method.
        #
        # If a function is not found, the command will raise an error but those
        # functions that are found will be defined. The error can be completely
        # suppressed with the `-ignoremissing` option.
        #
        # If the function name element is `#`, the triple is ignored, effectively
        # being considered a comment.
    }
    method stdcalls {fnlist args} {
        # Creates Tcl commands for multiple C functions within the loaded library
        # that all use the `__stdcall` calling convention.
        #  fnlist - list of function definitions
        #  -ignoremissing - do not raise an error if a function is not found
        # This is a wrapper around the [stdcall] method that provides some
        # syntactic sugar for defining multiple functions. The $fnlist
        # argument is a flat (not nested) list of function name, return type and
        # parameter list in the same form as described for the [stdcall]
        # method.
        #
        # If a function is not found, the command will raise an error but those
        # functions that are found will be defined. The error can be completely
        # suppressed with the `-ignoremissing` option.
        #
        # If the function name element is `#`, the triple is ignored, effectively
        # being considered a comment.
    }
}

