From: <ix...@us...> - 2009-07-31 03:59:03
|
Revision: 9595 http://exist.svn.sourceforge.net/exist/?rev=9595&view=rev Author: ixitar Date: 2009-07-31 03:58:55 +0000 (Fri, 31 Jul 2009) Log Message: ----------- [documentation] enhancing function module documentation. Modified Paths: -------------- trunk/eXist/src/org/exist/xquery/functions/FunIRIToURI.java trunk/eXist/src/org/exist/xquery/functions/FunInScopePrefixes.java trunk/eXist/src/org/exist/xquery/functions/FunIndexOf.java trunk/eXist/src/org/exist/xquery/functions/FunInsertBefore.java trunk/eXist/src/org/exist/xquery/functions/FunLang.java trunk/eXist/src/org/exist/xquery/functions/FunLast.java Modified: trunk/eXist/src/org/exist/xquery/functions/FunIRIToURI.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunIRIToURI.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunIRIToURI.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,6 +1,6 @@ /* * eXist Open Source Native XML Database - * Copyright (C) 2001-2007 The eXist Project + * Copyright (C) 2001-2009 The eXist Project * http://exist-db.org * * This program is free software; you can redistribute it and/or @@ -30,6 +30,8 @@ import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; import org.exist.xquery.util.URIUtils; +import org.exist.xquery.value.FunctionParameterSequenceType; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.Item; import org.exist.xquery.value.Sequence; import org.exist.xquery.value.SequenceType; @@ -38,14 +40,48 @@ public class FunIRIToURI extends Function { + protected static final String FUNCTION_DESCRIPTION = + + "This function converts an xs:string containing an " + + "IRI into a URI according to the rules spelled out " + + "in Section 3.1 of [RFC 3987]. It is idempotent but " + + "not invertible.\n\n" + + "If $iri contains a character that is invalid in an " + + "IRI, such as the space character (see note below), " + + "the invalid character is replaced by its percent-encoded " + + "form as described in [RFC 3986] before the conversion is performed.\n\n" + + "If $iri is the empty sequence, returns the zero-length string.\n\n" + + "Since [RFC 3986] recommends that, for consistency, " + + "URI producers and normalizers should use uppercase " + + "hexadecimal digits for all percent-encodings, this " + + "function must always generate hexadecimal values " + + "using the upper-case letters A-F.\n\n" + + "Notes:\n\n" + + + "This function does not check whether $iri is a legal " + + "IRI. It treats it as an xs:string and operates on " + + "the characters in the xs:string.\n\n" + + + "The following printable ASCII characters are invalid " + + "in an IRI: \"<\", \">\", \" \" \" (double quote), " + + "space, \"{\", \"}\", \"|\", \"\\\", \"^\", and \"`\". " + + "Since these characters should not appear in an IRI, " + + "if they do appear in $iri they will be percent-encoded. " + + "In addition, characters outside the range x20-x126 " + + "will be percent-encoded because they are invalid in a URI.\n\n" + + + "Since this function does not escape the PERCENT SIGN " + + "\"%\" and this character is not allowed in data within " + + "a URI, users wishing to convert character strings, " + + "such as file names, that include \"%\" to a URI " + + "should manually escape \"%\" by replacing it with \"%25\"."; + public final static FunctionSignature signature = new FunctionSignature( new QName("iri-to-uri", Function.BUILTIN_FUNCTION_NS), - "Returns an URI as a xs:string if the value of $a is a valid IRI. " + - "Invald characters are escape sequence encoded before the conversion. " + - "If $a is the empty sequence, returns the zero-length string.", - new SequenceType[] { new SequenceType(Type.STRING, Cardinality.ZERO_OR_ONE) }, - new SequenceType(Type.STRING, Cardinality.EXACTLY_ONE)); + FUNCTION_DESCRIPTION, + new SequenceType[] { new FunctionParameterSequenceType("iri", Type.STRING, Cardinality.ZERO_OR_ONE, "an IRI") }, + new FunctionReturnSequenceType(Type.STRING, Cardinality.EXACTLY_ONE, "the URI")); public FunIRIToURI(XQueryContext context, FunctionSignature signature) { super(context, signature); Modified: trunk/eXist/src/org/exist/xquery/functions/FunInScopePrefixes.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunInScopePrefixes.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunInScopePrefixes.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,3 +1,24 @@ +/* + * eXist Open Source Native XML Database + * Copyright (C) 2001-2009 The eXist Project + * http://exist-db.org + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software Foundation + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * + * $Id$ + */ package org.exist.xquery.functions; @@ -17,6 +38,8 @@ import org.exist.xquery.Profiler; import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; +import org.exist.xquery.value.FunctionParameterSequenceType; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.NodeValue; import org.exist.xquery.value.Sequence; import org.exist.xquery.value.SequenceType; @@ -31,11 +54,12 @@ public final static FunctionSignature signature = new FunctionSignature( new QName("in-scope-prefixes", Function.BUILTIN_FUNCTION_NS), - "Returns the prefixes of the in-scope namespaces for $a. For namespaces that have " + - "a prefix, it returns the prefix as an xs:NCName. For the default namespace, which has " + - "no prefix, it returns the zero-length string.", - new SequenceType[] { new SequenceType(Type.ELEMENT, Cardinality.EXACTLY_ONE) }, - new SequenceType(Type.STRING, Cardinality.ZERO_OR_MORE)); + "Returns the prefixes of the in-scope namespaces for $element. " + + "For namespaces that have a prefix, it returns the prefix as an " + + "xs:NCName. For the default namespace, which has no prefix, " + + "it returns the zero-length string", + new SequenceType[] { new FunctionParameterSequenceType("element", Type.ELEMENT, Cardinality.EXACTLY_ONE, "") }, + new FunctionReturnSequenceType(Type.STRING, Cardinality.ZERO_OR_MORE, "the prefixes")); public FunInScopePrefixes(XQueryContext context) { super(context, signature); Modified: trunk/eXist/src/org/exist/xquery/functions/FunIndexOf.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunIndexOf.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunIndexOf.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,6 +1,6 @@ /* * eXist Open Source Native XML Database - * Copyright (C) 2001-04 Wolfgang M. Meier + * Copyright (C) 2001-09 Wolfgang M. Meier * wol...@ex... * http://exist.sourceforge.net * @@ -36,6 +36,8 @@ import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; import org.exist.xquery.value.AtomicValue; +import org.exist.xquery.value.FunctionParameterSequenceType; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.IntegerValue; import org.exist.xquery.value.Sequence; import org.exist.xquery.value.SequenceIterator; @@ -51,30 +53,50 @@ */ public class FunIndexOf extends BasicFunction { + protected static final String FUNCTION_DESCRIPTION = + + "Returns a sequence of positive integers giving the " + + "positions within the sequence $seqParam of items " + + "that are equal to $srchParam.\n\n" + + "The collation used by the invocation of this function " + + "is determined according to the rules in 7.3.1 Collations. " + + "The collation is used when string comparison is required.\n\n" + + "The items in the sequence $seqParam are compared with " + + "$srchParam under the rules for the eq operator. Values of " + + "type xs:untypedAtomic are compared as if they were of " + + "type xs:string. Values that cannot be compared, i.e. " + + "the eq operator is not defined for their types, are " + + "considered to be distinct. If an item compares equal, " + + "then the position of that item in the sequence " + + "$seqParam is included in the result.\n\n" + + + "If the value of $seqParam is the empty sequence, or " + + "if no item in $seqParam matches $srchParam, then the " + + "empty sequence is returned.\n\n" + + + "The first item in a sequence is at position 1, not position 0.\n\n" + + + "The result sequence is in ascending numeric order."; + public final static FunctionSignature fnIndexOf[] = { new FunctionSignature( new QName("index-of", Function.BUILTIN_FUNCTION_NS), - "Returns a sequence of positive integers giving the positions within the sequence " + - "$a of items that are equal to $b. If the value of $a is the empty sequence, or if " + - "no item in $a matches $b, then the empty sequence is returned.", + FUNCTION_DESCRIPTION, new SequenceType[] { - new SequenceType(Type.ATOMIC, Cardinality.ZERO_OR_MORE), - new SequenceType(Type.ATOMIC, Cardinality.EXACTLY_ONE) + new FunctionParameterSequenceType("seqParam", Type.ATOMIC, Cardinality.ZERO_OR_MORE, ""), + new FunctionParameterSequenceType("srchParam", Type.ATOMIC, Cardinality.EXACTLY_ONE, "") }, - new SequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE) + new FunctionReturnSequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE, "a sequence of positive integers giving the positions within the sequence") ), new FunctionSignature( new QName("index-of", Function.BUILTIN_FUNCTION_NS), - "Returns a sequence of positive integers giving the positions within the sequence " + - "$a of items that are equal to $b. If the value of $a is the empty sequence, or if " + - "no item in $a matches $b, then the empty sequence is returned. Values are compared " + - "according to the collation specified in $c.", + FUNCTION_DESCRIPTION, new SequenceType[] { - new SequenceType(Type.ATOMIC, Cardinality.ZERO_OR_MORE), - new SequenceType(Type.ATOMIC, Cardinality.EXACTLY_ONE), - new SequenceType(Type.STRING, Cardinality.EXACTLY_ONE) + new FunctionParameterSequenceType("seqParam", Type.ATOMIC, Cardinality.ZERO_OR_MORE, ""), + new FunctionParameterSequenceType("srchParam", Type.ATOMIC, Cardinality.EXACTLY_ONE, ""), + new FunctionParameterSequenceType("collation", Type.STRING, Cardinality.EXACTLY_ONE, "") }, - new SequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE) + new FunctionReturnSequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE, "a sequence of positive integers giving the positions within the sequence") ) }; Modified: trunk/eXist/src/org/exist/xquery/functions/FunInsertBefore.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunInsertBefore.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunInsertBefore.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,3 +1,23 @@ +/* + * eXist Open Source Native XML Database + * Copyright (C) 2001-2009 the eXist team + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software Foundation + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + * + * $Id$ + */ package org.exist.xquery.functions; import org.exist.dom.QName; @@ -9,6 +29,8 @@ import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; import org.exist.xquery.value.DoubleValue; +import org.exist.xquery.value.FunctionParameterSequenceType; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.Item; import org.exist.xquery.value.Sequence; import org.exist.xquery.value.SequenceType; @@ -22,17 +44,35 @@ */ public class FunInsertBefore extends Function { + protected static final String FUNCTION_DESCRIPTION = + + "Returns a new sequence constructed from the value " + + "of $target with the value of $inserts inserted at " + + "the position specified by the value of $position. " + + "(The value of $target is not affected by the sequence construction.)\n\n" + + + "If $target is the empty sequence, $inserts is returned. If $inserts is the empty sequence, $target is returned.\n\n" + + + "The value returned by the function consists of all items " + + "of $target whose index is less than $position, followed " + + "by all items of $inserts, followed by the remaining elements " + + "of $target, in that sequence.\n\n" + + + "If $position is less than one (1), the first position, the effective " + + "value of $position is one (1). If $position is greater than the number " + + "of items in $target, then the effective value of $position is " + + "equal to the number of items in $target plus 1."; + public final static FunctionSignature signature = new FunctionSignature( new QName("insert-before", Function.BUILTIN_FUNCTION_NS), - "Returns a new sequence constructed from the value of the target sequence" + - "with the value of the sequence to insert inserted at the position specified.", + FUNCTION_DESCRIPTION, new SequenceType[] { - new SequenceType(Type.ITEM, Cardinality.ZERO_OR_MORE), - new SequenceType(Type.INTEGER, Cardinality.ONE), - new SequenceType(Type.ITEM, Cardinality.ZERO_OR_MORE) + new FunctionParameterSequenceType("target", Type.ITEM, Cardinality.ZERO_OR_MORE, ""), + new FunctionParameterSequenceType("position", Type.INTEGER, Cardinality.ONE, ""), + new FunctionParameterSequenceType("inserts", Type.ITEM, Cardinality.ZERO_OR_MORE, "") }, - new SequenceType(Type.ITEM, Cardinality.ZERO_OR_MORE)); + new FunctionReturnSequenceType(Type.ITEM, Cardinality.ZERO_OR_MORE, "the new sequence")); public FunInsertBefore(XQueryContext context) { super(context, signature); Modified: trunk/eXist/src/org/exist/xquery/functions/FunLang.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunLang.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunLang.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,6 +1,6 @@ /* * eXist Open Source Native XML Database - * Copyright (C) 2001-2006 the eXist team + * Copyright (C) 2001-2009 the eXist team * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public License @@ -33,6 +33,8 @@ import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; import org.exist.xquery.value.BooleanValue; +import org.exist.xquery.value.FunctionParameterSequenceType; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.Item; import org.exist.xquery.value.Sequence; import org.exist.xquery.value.SequenceType; @@ -46,24 +48,44 @@ public static String queryString = "(ancestor-or-self::*/@xml:lang)[position() = last()]"; public CompiledXQuery query; + + protected static final String FUNCTION_DESCRIPTION = + "This function tests whether the language of $node, or the context item if " + + "the second argument is omitted, as specified by xml:lang attributes is the " + + "same as, or is a sublanguage of, the language specified by $testlang. The " + + "behavior of the function if the second argument is omitted is exactly the " + + "same as if the context item (.) had been passed as the second argument. The " + + "language of the argument node, or the context item if the second argument is " + + "omitted, is determined by the value of the xml:lang attribute on the node, " + + "or, if the node has no such attribute, by the value of the xml:lang attribute " + + "on the nearest ancestor of the node that has an xml:lang attribute. If there " + + "is no such ancestor, then the function returns false\n\n" + + + "The following errors may be raised: if the context item is undefined [err:XPDY0002]XP; " + + "if the context item is not a node [err:XPTY0004]XP.\n\n" + + + "If $testlang is the empty sequence it is interpreted as the zero-length string."; + public final static FunctionSignature signatures[] = { new FunctionSignature( new QName("lang", Function.BUILTIN_FUNCTION_NS), - "Returns true if the context items xml:lang attribute is equal " + - "to the value of $a, false otherwise.", + FUNCTION_DESCRIPTION, new SequenceType[] { - new SequenceType(Type.STRING, Cardinality.ZERO_OR_ONE)}, - new SequenceType(Type.BOOLEAN, Cardinality.ONE)), + new FunctionParameterSequenceType("testLang", Type.STRING, Cardinality.ZERO_OR_ONE, "the language code") + }, + new FunctionReturnSequenceType(Type.BOOLEAN, Cardinality.ONE, "true if the language code matches") + ), new FunctionSignature( new QName("lang", Function.BUILTIN_FUNCTION_NS), - "Returns true if the context items xml:lang attribute is equal " + - "to the value of $a, false otherwise.", + FUNCTION_DESCRIPTION, new SequenceType[] { - new SequenceType(Type.STRING, Cardinality.ZERO_OR_ONE), - new SequenceType(Type.NODE, Cardinality.EXACTLY_ONE)}, - new SequenceType(Type.BOOLEAN, Cardinality.ONE)) - }; + new FunctionParameterSequenceType("testLang", Type.STRING, Cardinality.ZERO_OR_ONE, "the language code"), + new FunctionParameterSequenceType("node", Type.NODE, Cardinality.EXACTLY_ONE, "") + }, + new FunctionReturnSequenceType(Type.BOOLEAN, Cardinality.ONE, "true if the language code matches") + ) + }; public FunLang(XQueryContext context, FunctionSignature signature) { super(context, signature); Modified: trunk/eXist/src/org/exist/xquery/functions/FunLast.java =================================================================== --- trunk/eXist/src/org/exist/xquery/functions/FunLast.java 2009-07-31 02:42:17 UTC (rev 9594) +++ trunk/eXist/src/org/exist/xquery/functions/FunLast.java 2009-07-31 03:58:55 UTC (rev 9595) @@ -1,6 +1,6 @@ /* * eXist Open Source Native XML Database - * Copyright (C) 2000-2006 The eXist team + * Copyright (C) 2000-2009 The eXist team * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public License @@ -29,10 +29,10 @@ import org.exist.xquery.Profiler; import org.exist.xquery.XPathException; import org.exist.xquery.XQueryContext; +import org.exist.xquery.value.FunctionReturnSequenceType; import org.exist.xquery.value.IntegerValue; import org.exist.xquery.value.Item; import org.exist.xquery.value.Sequence; -import org.exist.xquery.value.SequenceType; import org.exist.xquery.value.Type; /** @@ -48,7 +48,7 @@ "Returns the context size from the dynamic context. " + "If the context item is undefined, an error is raised.", null, - new SequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE)); + new FunctionReturnSequenceType(Type.INTEGER, Cardinality.ZERO_OR_ONE, "the context size from the dynamic context")); public FunLast(XQueryContext context) { super(context, signature); This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |