From c185ae1549bf2f99c42ab9a239bc698e2c0957c7 Mon Sep 17 00:00:00 2001 From: Matthias Benkard Date: Sun, 5 Aug 2007 16:18:12 +0200 Subject: Improve documentation. darcs-hash:2d562d82a7d51808058ac9c42bd54008486ec646 --- Lisp/libobjcl.lisp | 43 +++++++++++++----------- Lisp/method-invocation.lisp | 80 +++++++++++++++++++++++++-------------------- 2 files changed, 68 insertions(+), 55 deletions(-) (limited to 'Lisp') diff --git a/Lisp/libobjcl.lisp b/Lisp/libobjcl.lisp index 296a670..21d0113 100644 --- a/Lisp/libobjcl.lisp +++ b/Lisp/libobjcl.lisp @@ -63,43 +63,48 @@ (defun find-objc-class (class-name) "Retrieve an Objective C class by name. -CLASS-NAME: a symbol or a string. +## Arguments and Values: -Returns: an OBJC-CLASS object representing the class whose name is -CLASS-NAME. +*class-name* --- a **symbol** or a **string**. +Returns: *class* --- an __objc-class__ object representing the Objective +C class whose name is *class-name*. -If CLASS-NAME is a symbol which does not contain a hyphen, its symbol -name is converted to lower case except for the first letter, which is -left intact, and the resulting string used as if directly given as an -argument to FIND-OBJC-CLASS. -If CLASS-NAME is a symbol which containts a hyphen, its symbol name is -split into components seperated by hyphens and each component is -converted into a string according to the following rules: +## Description: - 1. The first component is fully converted to upper case except for its - first letter, which is left intact. +If *class-name* is a **symbol** which does not contain a hyphen, its +**name** is converted to **lowercase** except for the first letter, +which is left intact, and the resulting **string** used as if directly +given as an **argument** to __find-objc-class__. - 2. Any additional components have all of their letters converted to - lower case, except for their first letters, which are left intact. +If *class-name* is a **symbol** which containts a hyphen, its **name** +is split into components separated by hyphens and each component +converted into a **string** according to the following rules: + +1. The first component is fully converted to **uppercase** except for + its first letter, which is left intact. + +2. Any additional components have all of their letters converted to + **lowercase**, except for their first letters, which are left intact. After that, the components are concatenated in order and the resulting -string used as if directly given as an argument to FIND-OBJC-CLASS. +**string** used as if directly given as an **argument** to +__find-objc-class__. -Examples: +## Examples: - (find-objc-class \"NSObject\") ;=> # + (find-objc-class \"NSObject\") ;=> # (find-objc-class 'ns-object) ;=> # (find-objc-class 'nsobject) ;=> NIL -Rationale: +## Rationale: The first component of an Objective C class name is conventionally thought of as a namespace identifier. It is therefore sensible to -expect it to be converted to upper case by default, which is the +expect it to be converted to **uppercase** by default, which is the conventional case for namespace identifiers in Objective C." (typecase class-name diff --git a/Lisp/method-invocation.lisp b/Lisp/method-invocation.lisp index 8de77dd..6461743 100644 --- a/Lisp/method-invocation.lisp +++ b/Lisp/method-invocation.lisp @@ -5,36 +5,40 @@ (defun invoke (receiver message-start &rest message-components) "Send a message to an Objective C instance. +## Arguments and Values: + *receiver* --- an Objective C wrapper object. -*message-start* --- a symbol. +*message-start* --- a **symbol**. -*message-components* --- an alternating list of arguments and message -name component symbols. +*message-components* --- an alternating **list** of **object**s and +**symbol**s. Returns: *result* --- the return value of the method invocation. -Each message name component is first split into parts seperated by -hyphens and each part is converted into a string according to the -following rules: +## Description: -1. The first part is fully converted to lower case. +All even-numbered *message components* are collected in order and the +resulting **list** used as if as additional **argument**s to +__invoke-by-name__. -2. Any additional parts are also fully converted to lower case except - for their first letters, which are left intact. +All uneven-numbered *message components*, which must be **symbol**s, are +first split into parts separated by hyphens and each part converted into +a **string** according to the following rules: -3. If the symbol is a keyword symbol, the resulting string is suffixed - by a colon (`:'). +1. The first part is fully converted to **lowercase**. + +2. Any additional parts are also fully converted to **lowercase** except + for their first letters, which are left intact. -After that, all parts are concatenated in order to form a single message -component. The message components are in turn concatenated in order to -form the message name which is used as if the second argument to a call -to _invoke-by-name_. +3. If the symbol is a **keyword**, the resulting **string** is suffixed + by a **colon** (`:'). -The message components that are not message name components are -collected in order and the resulting list used as if as additional -arguments to _invoke-by-name_. +After that, all parts are concatenated in order to form a +single *message name component*. The *message name components* are in +turn concatenated in order to form the *message name* which is used as +if as the second **argument** to __invoke-by-name__. ## Examples: @@ -59,7 +63,7 @@ arguments to _invoke-by-name_. ## See also: -INVOKE-BY-NAME" + __invoke-by-name__" (flet ((message-component->string (symbol) (let* ((components (split-sequence #\- (symbol-name symbol) @@ -95,33 +99,37 @@ INVOKE-BY-NAME" (defun invoke-by-name (receiver method-name &rest args) "Send a message to an Objective C object by the name of the method. -RECEIVER: an Objective C wrapper object. +## Arguments and Values: -METHOD-NAME: a string. +*receiver* --- an Objective C wrapper object. -ARGS: a list of objects. +*method-name* --- a **string**. -Returns: the return value of the method invocation. +*args* --- a list of **object**s. +Returns: *result* --- the return value of the method invocation. -Examples: - (invoke-by-name (find-objc-class 'ns-string) - \"stringWithCString:\" \"Mulk.\") - ;=> # +## Examples: - (invoke-by-name (find-objc-class 'ns-object) - \"self\") - ;=> # + (invoke-by-name (find-objc-class 'ns-string) + \"stringWithCString:\" \"Mulk.\") + ;=> # + + (invoke-by-name (find-objc-class 'ns-object) + \"self\") + ;=> # + + (invoke-by-name (find-objc-class 'ns-string) + \"stringWithCString:encoding:\" + \"Mulk.\" + 4) + ;=> # - (invoke-by-name (find-objc-class 'ns-string) - \"stringWithCString:encoding:\" - \"Mulk.\" - 4) - ;=> # +## See also: -See also: INVOKE" + __invoke__" (let* ((arglist (arglist-intersperse-types (mapcar #'lisp->obj-data args))) -- cgit v1.2.3