On Mon, Dec 15, 2008 at 19:10, Johannes Schlüter <[email protected]> wrote:
> Hi,
>
> could anybody of you review the patches Christian (CC'd) sent me from a
> doc perspective? From the contents they seem to be fine but I have
> little knowledge about XML formatting rules and similar things...
After a _quick_ scrollthrough, it looks good.
Few points:
+ <para>
+This extension gives access to the GNU Libidn which is
Missing WS
+ The error code as returned by idn_to_ascii() or idn_to_utf8().
<function>idn_to_ascii</function> or <function>idn_to_utf8</function>.
+ <type>string|boolean</type><methodname>idn_to_ascii</methodname>
That proto looks weird. Is boolean returned in any other cases then
failure? If so then its probably right, but we don't document
returntypes on errors (otherwise _all_ functions would have null
too..). Error related stuff should go into <refsect1 role="error">
+ The UTF-8 encoded domain name. CAVEAT: If e.g. an ISO-8859-1
(aka Western Europe latin1) encoded string is
+ passed it will be converted into an ACE encoded "xn--" string.
It will not be the one you expected though!
I would use <warning><para>If e.g...</..>
+ If a reference to a variable is passed, the variable is set to
the IDNA error code.
"Will be set to the IDNA error code" or something along those lines,
no need to say "If a refernece to a .." (sounds weird, too).
+if ($ascii === false) printf("Detected error %d: %s\n", $errorcode,
idn_strerror($errorcode));
Please use the PEAR Coding standard.
+ <!-- &example.outputs.similar; -->
Why commenting it out? (It is in actual entity name, not example entity name :))
-Hannes
