Permalink
Browse files

Massive overhaul of all documentation.

All documentation now works reasonibly well with Doxygen.
  • Loading branch information...
1 parent 9ce617f commit 01d5816fdaf33384944201638ed0ceaa33b9a07b @technosophos technosophos committed Oct 18, 2010
View
@@ -142,7 +142,7 @@ To print this message, do:
<stripphpcomments/>
<!-- Removed per issue #20 -->
<!-- stripwhitespace/ -->
- <replacetokens begintoken="@" endtoken="@">
+ <replacetokens begintoken="-" endtoken="%">
<token key="UNSTABLE" value="${version}"/>
</replacetokens>
</filterchain>
@@ -184,7 +184,7 @@ To print this message, do:
<!-- Copy source code, doing token replacement on version. -->
<copy todir="${releasedir}/src">
<filterchain>
- <replacetokens begintoken="@" endtoken="@">
+ <replacetokens begintoken="-" endtoken="%">
<token key="UNSTABLE" value="${version}"/>
</replacetokens>
</filterchain>
@@ -235,37 +235,12 @@ To print this message, do:
<target name="doc" depends="lint,setup" description="Generate API docs.">
<delete dir="${docsdir}"/>
<doxygen config="./config.doxy"/>
- <!--
- <phpdoc title="QueryPath ${version}"
- sourcecode="yes"
- destdir="${docsdir}"
- output="${phpdoc.style}"
- defaultcategoryname="QueryPath"
- defaultpackagename="QueryPath"
- examplesdir="examples"
- quiet="true"
- >
- <fileset refid="sourcecode"/>
- <fileset refid="tutorials"/>
- <fileset refid="examplecode"/>
- <projdocfileset dir=".">
- <include name="README.md"/>
- <include name="README"/>
- <include name="INSTALL"/>
- <include name="COPYING-LGPL.txt"/>
- <include name="COPYING-MIT.txt"/>
- <include name="LGPL-2.1.txt"/>
- <include name="RELEASE-*"/>
- <include name="API-*"/>
- </projdocfileset>
- </phpdoc>
- -->
<!-- Need to replace version information in generated documentation -->
<reflexive>
<fileset refid="docs"/>
<filterchain>
- <replacetokens begintoken="@" endtoken="@">
+ <replacetokens begintoken="-" endtoken="%">
<token key="UNSTABLE" value="${version}"/>
</replacetokens>
</filterchain>
@@ -393,7 +368,7 @@ To print this message, do:
<filterchain>
<stripphpcomments/>
<stripwhitespace/>
- <replacetokens begintoken="@" endtoken="@">
+ <replacetokens begintoken="-" endtoken="%">
<token key="UNSTABLE" value="${version}"/>
<token key="PHAR_FILENAME" value="QueryPath.phar"/>
</replacetokens>
@@ -462,7 +437,7 @@ To print this message, do:
<filterchain>
<!-- stripphpcomments/ -->
<!-- stripwhitespace/ -->
- <replacetokens begintoken="@" endtoken="@">
+ <replacetokens begintoken="-" endtoken="%">
<token key="UNSTABLE" value="${version}"/>
</replacetokens>
</filterchain>
View
@@ -38,7 +38,7 @@ PROJECT_NUMBER = 2.1.0beta3
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
-OUTPUT_DIRECTORY = docs
+OUTPUT_DIRECTORY = doc
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
# 4096 sub-directories (in 2 levels) under the output directory of each output
@@ -2,7 +2,7 @@
/**
* Use QueryPath's database extension to import XML data into a database.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -16,7 +16,7 @@
* Data stored there for a particular Wikipedia entry (any Wikipedia
* wiki name should work here).
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://www.w3.org/DesignIssues/LinkedData.html
View
@@ -2,7 +2,7 @@
/**
* Urban Dictionary Random Word Generator
*
- * @package Examples
+ *
* @author Emily Brand
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://www.urbandictionary.com/
View
@@ -2,7 +2,7 @@
/**
* Compare jQuery documentation to QueryPath documentation
*
- * @package Examples
+ *
* @author Emily Brand
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://api.jquery.com/api/
View
@@ -4,7 +4,7 @@
*
* For namespaces use | instead of :
*
- * @package Examples
+ *
* @author Emily Brand
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://www.urbandictionary.com/
View
@@ -11,7 +11,7 @@
* parse it. From there, we make a list of hyperlinks, one for each item in
* the original feed.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -12,7 +12,6 @@
* templates, injecting database information with {@link QPDB}, and merging
* data from one QueryPath to another.
*
- * @ingroup Examples
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
@@ -12,7 +12,7 @@
* and exact match, so the method outline below is roughly the same as merely
* using `:contains(Release)`.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -10,7 +10,7 @@
*
* TODO: Fix the output.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://musicbrainz.org
View
@@ -12,7 +12,7 @@
* The file used here was generated by OpenOffice 3.x. Other word processors are
* also capable of generating ODT files.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -10,7 +10,7 @@
*
* This example illustrates how such a file can be parsed and manipulated.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -13,7 +13,7 @@
* methods of looping. An even more advanced method would be to use the
* {@link QPTPL} library.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
@@ -13,7 +13,7 @@
* This file is fully explained in the official QueryPath tutorial, located
* at {@link https://fedorahosted.org/querypath/wiki/QueryPathTutorial}
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see qp()
View
@@ -10,7 +10,7 @@
* QueryPath. POST queries are supported, too. Use a stream context
* to create those.
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
* @see http://www.w3.org/2009/sparql/wiki/Main_Page
View
@@ -11,7 +11,7 @@
* at {@link http://querypath.org/svg.php}. (That URL actually runs the script displayed
* here.)
*
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
View
@@ -14,7 +14,7 @@
* altered during a loop.
*
* @see QueryPath
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL (The GNU Lesser GPL) or an MIT-like license.
*/
View
@@ -14,7 +14,7 @@
* </code>
* (A space was inserted above to prevent the documentation renderer from
* misinterpreting it.)
- * @package Examples
+ *
* @author M Butcher <matt@aleph-null.tv>
* @license LGPL The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
@@ -32,7 +32,7 @@
* is no calculation done.
*
* For detailed examples of how the code works and what selectors are supported,
- * see the {@see CssEventTests.php} file, which contains the unit tests used for
+ * see the CssEventTests file, which contains the unit tests used for
* testing this implementation.
*
* @author M Butcher <matt@aleph-null.tv>
@@ -53,13 +53,13 @@
* match and the previously matched elements.
*
* To use this handler:
- * <code>
+ * @code
* $filter = '#id'; // Some CSS selector
* $handler = new QueryPathCssParser(DOMNode $dom);
* $parser = new CssParser();
* $parser->parse($filter, $handler);
* $matches = $handler->getMatches();
- * </code>
+ * @endcode
*
* $matches will be an array of zero or more DOMElement objects.
*
@@ -1419,5 +1419,7 @@ public function attachNodeList(DOMNodeList $nodeList, SplObjectStorage $splos) {
*
* This is thrown in cases where some feature is expected, but the current
* implementation does not support that feature.
+ *
+ * @ingroup querypath_css
*/
class NotImplementedException extends Exception {}
@@ -13,9 +13,13 @@
* @license http://opensource.org/licenses/lgpl-2.1.php The GNU Lesser GPL (LGPL) or an MIT-like license.
*/
-/** addtogroup querypath_css CSS Parsing
+/** @addtogroup querypath_css CSS Parsing
* QueryPath includes a CSS 3 Selector parser.
*
+ *
+ * Typically the parser is not accessed directly. Most developers will use it indirectly from
+ * qp(), htmlqp(), or one of the methods on a QueryPath object.
+ *
* This parser is modular and is not tied to QueryPath, so you can use it in your
* own (non-QueryPath) projects if you wish. To dive in, start with CssEventHandler, the
* event interface that works like a SAX API for CSS selectors. If you want to check out
@@ -34,6 +38,8 @@
*
* This library is inspired by the SAX2 API for parsing XML. Each component of a
* selector fires an event, passing the necessary data on to the event handler.
+ *
+ * @ingroup querypath_css
*/
interface CssEventHandler {
/** The is-exactly (=) operator. */
@@ -113,13 +119,13 @@ public function attribute($name, $value = NULL, $operation = CssEventHandler::is
* Example: [ns|name~=attr]
* @param string $name
* The attribute name.
+ * @param string $ns
+ * The namespace identifier (not the URI).
* @param string $value
* The value of the attribute, if given.
* @param int $operation
* The operation to be used for matching. See {@link CssEventHandler}
* constants for a list of supported operations.
- * @param string $namespace
- * The namespace identifier (not the URI).
*/
public function attributeNS($name, $ns, $value = NULL, $operation = CssEventHandler::isExactly);
/**
@@ -170,6 +176,8 @@ public function anyDescendant(); // ' ' (space) operator.
* Tokens for CSS.
* This class defines the recognized tokens for the parser, and also
* provides utility functions for error reporting.
+ *
+ * @ingroup querypath_css
*/
final class CssToken {
const char = 0;
@@ -231,6 +239,8 @@ static function name($const_int) {
* This class provides an event-based parser for CSS selectors. It can be
* used, for example, as a basis for writing a DOM query engine based on
* CSS.
+ *
+ * @ingroup querypath_css
*/
class CssParser {
protected $scanner = NULL;
@@ -787,6 +797,8 @@ private function throwError($expected, $got) {
* Scanner for CSS selector parsing.
*
* This provides a simple scanner for traversing an input stream.
+ *
+ * @ingroup querypath_css
*/
final class CssScanner {
var $is = NULL;
@@ -1090,5 +1102,7 @@ function isEmpty() {
/**
* Exception indicating an error in CSS parsing.
+ *
+ * @ingroup querypath_css
*/
class CSSParseException extends EXCEPTION {}
Oops, something went wrong.

0 comments on commit 01d5816

Please sign in to comment.