Doc #76341 [Opn]: Tidy class doc: a contribute

Edit report at https://bugs.php.net/bug.php?id=76341&edit=1 ID: 76341 User updated by: salsi at icosaedro dot it Reported by: salsi at icosaedro dot it Summary: Tidy class doc: a contribute Status: Open Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Block user comment: N Private report: N New Comment: CORRIGE: In the pseudo-PHP code I wrote above, all the default values of the optional arguments are dummy values, mostly NULL, as there is no other way to mark optional arguments rather than assigning some default value; these values should then be ignored. Previous Comments: ------------------------------------------------------------------------ [2018-05-15 10:56:56] salsi at icosaedro dot it Description: ------------ To integrate the documentation about the tidy class, here is what I found so far by testing with actual code; please consider for a possible merge with the current documentation as there are several detailed annotations: class tidy { /** * Informational, warning and error messages collected while parsing. * Lines are separated by '\r\n'; a trailing '\r' is also added for some * reason. The NULL value means either no parsing has still being performed * or the parsing succeeded. * @var string */ public $errorBuffer; /** * Initializes a new parser and possibly also parse the specified file. * Hint: to parse a string, do not specify any argument and then use the * parseString() method instead. * @param string $filename File to parse. If this argument is provided, it * must be a valid existing file name. * @param mixed $config String of the configuration options or associative * array of the options. Set the empty array here if you want to set the * following arguments too. * @param string $encoding Encoding for input and output documents. * Note that the tidy library still can't parse a possible HTML META element * specifying the encoding, so setting this argument is advised. * Default input encoding: unspecified, possibly unexpected. * Default output encoding: UTF8. * BEWARE: "UTF-8" is not a recognized encoding; "UTF8" is the right spelling. * @param boolean $use_include_path If true, a relative $filename path is * resolved first against the directories listed in the include_path php.ini * directive, and then search in the current directory. Default: FALSE. * @return void * @triggers E_WARNING Failed reading $filename. Failed reading the $config * file when this argument is a string. Invalid $encoding. * @triggers E_NOTICE Unknown or invalid $config when this argument is an * associative array. */ function __construct($filename = NULL, $config = NULL, $encoding = NULL, $use_include_path = FALSE){} /** * Returns the node starting with the BODY element. * @return tidyNode The BODY element, either parsed or added by this library. * Returns NULL if still no parsing performed. */ function body(){} // Other methods: cleanRepair(), diagnose(), getConfig(), getHtmlVer() /** * Returns the value of the specified option. * @param string $option Name of the option to retrieve. * @return mixed Value of the option. * @triggers E_WARNING No this option. */ function getOpt(/*. string .*/ $option){} /** * Returns the documentation for the given option name. * @param string $optname * @return string * @deprecated This method is not available; tested with getRelease() gives 2017/03/01 * on Wamp Server with PHP 7.1.9. */ function getOptDoc($optname){} /** * Return the release date of the tidy library. * @return string */ function getRelease(){} /** * Returns the status of the document. * @return int */ function getStatus(){} /** * Returns the HEAD element. * @return tidyNode The HEAD element, or NULL if not available. */ function head(){} /** * Returns the HTML element. * @return tidyNode The HTML element, or NULL if not available. */ function html(){} /** * Tells if the document is XHTML. * @return boolean */ function isXhtml(){} /** * Tells if the document is XML. * @return boolean */ function isXml(){} /** * Parse the given file. * @param string $filename File to parse. * @param mixed $config String of the configuration options or associative * array of the options. Set the empty array here if you want to set the * following arguments too. * @param string $encoding Encoding for input and output documents. * Note that the tidy library still can't parse a possible HTML META element * specifying the encoding, so setting this argument is advised. * Default input encoding: unspecified, possibly unexpected. * Default output encoding: UTF-8. * BEWARE: "UTF-8" is not a recognized encoding; "UTF8" is the right spelling. * @param boolean $use_include_path If true, a relative $filename path is * resolved first against the directories listed in the include_path php.ini * directive, and then search in the current directory. Default: FALSE. * @return boolean Always returns TRUE. * @triggers E_WARNING Failed reading $filename. Failed reading the $config * file when this argument is a string. Invalid $encoding. * @triggers E_NOTICE Unknown or invalid $config when this argument is an * associative array. */ function parseFile($filename, $config = NULL, $encoding = NULL, $use_include_path = FALSE){} /** * Parse the given string. * @param string $input Text to parse. * @param mixed $config String of the configuration options or associative * array of the options. Set the empty array here if you want to set the * following arguments too. * @param string $encoding Encoding for input and output documents. * Note that the tidy library still can't parse a possible HTML META element * specifying the encoding, so setting this argument is advised. * Default input encoding: unspecified, possibly unexpected. * Default output encoding: UTF-8. * BEWARE: "UTF-8" is not a recognized encoding; "UTF8" is the right spelling. * @return boolean Always returns TRUE. * @triggers E_WARNING Failed reading the $config file when this argument is * a string. Invalid $encoding. * @triggers E_NOTICE Unknown or invalid $config when this argument is an * associative array. */ function parseString($input, $config = NULL, $encoding = NULL){} /** * Parse the given file and returns the repaired result. * @param string $filename File to parse. If this argument is provided, it * must be a valid existing file name. * @param mixed $config String of the configuration options or associative * array of the options. Set the empty array here if you want to set the * following arguments too. * @param string $encoding Encoding for input and output documents. * Note that the tidy library still can't parse a possible HTML META element * specifying the encoding, so setting this argument is advised. * Default input encoding: unspecified, possibly unexpected. * Default output encoding: UTF-8. * BEWARE: "UTF-8" is not a recognized encoding; "UTF8" is the right spelling. * @param boolean $use_include_path If true, a relative $filename path is * resolved first against the directories listed in the include_path php.ini * directive, and then search in the current directory. Default: FALSE. * @return string Repaired contents of the file. * @triggers E_WARNING Failed reading $filename. Failed reading the $config * file when this argument is a string. Invalid $encoding. * @triggers E_NOTICE Unknown or invalid $config when this argument is an * associative array. */ function repairFile($filename, $config = NULL, $encoding = NULL, $use_include_path = FALSE){} /** * Parse the given string and returns the repaired result. * @param string $input Text to parse. * @param mixed $config String of the configuration options or associative * array of the options. Set the empty array here if you want to set the * following arguments too. * @param string $encoding Encoding for input and output documents. * Note that the tidy library still can't parse a possible HTML META element * specifying the encoding, so setting this argument is advised. * Default input encoding: unspecified, possibly unexpected. * Default output encoding: UTF-8. * BEWARE: "UTF-8" is not a recognized encoding; "UTF8" is the right spelling. * @return string Repaired contents of the string. * @triggers E_WARNING Failed reading the $config file when this argument is * a string. Invalid $encoding. * @triggers E_NOTICE Unknown or invalid $config when this argument is an * associative array. */ function repairString($input, $config = NULL, $encoding = NULL){} /** * Returns the root node of the parsed tree. * @return tidyNode Root note of the parsed tree, possibly a tidyNode with * empty name property if nothing has been parsed yet. */ function root(){} } ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=76341&edit=1