walkero
/
libpsl
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Make API docs more detailed

This commit is contained in:
Tim Rühsen 2016-11-14 12:08:20 +01:00
parent 3f276c7d1e
commit 5d32b80077
1 changed files with 18 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/psl.c
View File

@ -942,8 +942,9 @@ suffix_yes:
* *
* For cookie domain checking see psl_is_cookie_domain_acceptable(). * For cookie domain checking see psl_is_cookie_domain_acceptable().
* *
* International @domain names have to be either in lowercase UTF-8 or in ASCII form (punycode). * International @domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode).
* Other encodings likely result in incorrect return values. * Other encodings likely result in incorrect return values.
* Use helper function psl_str_to_utf8lower() for normalization @domain.
* *
* @psl is a context returned by either psl_load_file(), psl_load_fp() or * @psl is a context returned by either psl_load_file(), psl_load_fp() or
* psl_builtin(). * psl_builtin().
@ -972,8 +973,9 @@ int psl_is_public_suffix(const psl_ctx_t *psl, const char *domain)
* @type specifies the PSL section where to perform the lookup. Valid values are * @type specifies the PSL section where to perform the lookup. Valid values are
* %PSL_TYPE_PRIVATE, %PSL_TYPE_ICANN and %PSL_TYPE_ANY. * %PSL_TYPE_PRIVATE, %PSL_TYPE_ICANN and %PSL_TYPE_ANY.
* *
* International @domain names have to be either in lowercase UTF-8 or in ASCII form (punycode). * International @domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode).
* Other encodings likely result in incorrect return values. * Other encodings likely result in incorrect return values.
* Use helper function psl_str_to_utf8lower() for normalization @domain.
* *
* @psl is a context returned by either psl_load_file(), psl_load_fp() or * @psl is a context returned by either psl_load_file(), psl_load_fp() or
* psl_builtin(). * psl_builtin().
@ -998,8 +1000,9 @@ int psl_is_public_suffix2(const psl_ctx_t *psl, const char *domain, int type)
* This function finds the longest public suffix part of @domain by the means * This function finds the longest public suffix part of @domain by the means
* of the [Mozilla Public Suffix List](https://publicsuffix.org). * of the [Mozilla Public Suffix List](https://publicsuffix.org).
* *
* International @domain names have to be either in lowercase UTF-8 or in ASCII form (punycode). * International @domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode).
* Other encodings likely result in incorrect return values. * Other encodings likely result in incorrect return values.
* Use helper function psl_str_to_utf8lower() for normalization @domain.
* *
* @psl is a context returned by either psl_load_file(), psl_load_fp() or * @psl is a context returned by either psl_load_file(), psl_load_fp() or
* psl_builtin(). * psl_builtin().
@ -1037,8 +1040,9 @@ const char *psl_unregistrable_domain(const psl_ctx_t *psl, const char *domain)
* This function finds the shortest private suffix part of @domain by the means * This function finds the shortest private suffix part of @domain by the means
* of the [Mozilla Public Suffix List](https://publicsuffix.org). * of the [Mozilla Public Suffix List](https://publicsuffix.org).
* *
* International @domain names have to be either in lowercase UTF-8 or in ASCII form (punycode). * International @domain names have to be either in UTF-8 (lowercase + NFCK) or in ASCII/ACE format (punycode).
* Other encodings likely result in incorrect return values. * Other encodings likely result in incorrect return values.
* Use helper function psl_str_to_utf8lower() for normalization @domain.
* *
* @psl is a context returned by either psl_load_file(), psl_load_fp() or * @psl is a context returned by either psl_load_file(), psl_load_fp() or
* psl_builtin(). * psl_builtin().
@ -1078,7 +1082,7 @@ const char *psl_registrable_domain(const psl_ctx_t *psl, const char *domain)
* This function loads the public suffixes file named @fname. * This function loads the public suffixes file named @fname.
* To free the allocated resources, call psl_free(). * To free the allocated resources, call psl_free().
* *
* The suffixes are expected to be lowercase UTF-8 encoded if they are international. * The suffixes are expected to be UTF-8 encoded (lowercase + NFCK) if they are international.
* *
* Returns: Pointer to a PSL context or %NULL on failure. * Returns: Pointer to a PSL context or %NULL on failure.
* *
@ -1107,7 +1111,7 @@ psl_ctx_t *psl_load_file(const char *fname)
* This function loads the public suffixes from a FILE pointer. * This function loads the public suffixes from a FILE pointer.
* To free the allocated resources, call psl_free(). * To free the allocated resources, call psl_free().
* *
* The suffixes are expected to be lowercase UTF-8 encoded if they are international. * The suffixes are expected to be UTF-8 encoded (lowercase + NFCK) if they are international.
* *
* Returns: Pointer to a PSL context or %NULL on failure. * Returns: Pointer to a PSL context or %NULL on failure.
* *
@ -1286,8 +1290,8 @@ void psl_free(psl_ctx_t *psl)
* The builtin data also contains punycode entries, one for each international domain name. * The builtin data also contains punycode entries, one for each international domain name.
* *
* If the generation of built-in data has been disabled during compilation, %NULL will be returned. * If the generation of built-in data has been disabled during compilation, %NULL will be returned.
* When using the builtin psl context, you can provide UTF-8 or punycode representations of domains to * When using the builtin psl context, you can provide UTF-8 (lowercase + NFCK) or ASCII/ACE (punycode)
* functions like psl_is_public_suffix(). * representations of domains to functions like psl_is_public_suffix().
* *
* Returns: Pointer to the built in PSL data or NULL if this data is not available. * Returns: Pointer to the built in PSL data or NULL if this data is not available.
* *
@ -1506,8 +1510,10 @@ static int _isip(const char *hostname)
* This helper function checks whether @cookie_domain is an acceptable cookie domain value for the request * This helper function checks whether @cookie_domain is an acceptable cookie domain value for the request
* @hostname. * @hostname.
* *
* For international domain names both, @hostname and @cookie_domain, have to be either in lowercase UTF-8 * For international domain names both, @hostname and @cookie_domain, have to be either in UTF-8 (lowercase + NFCK)
* or in ASCII form (punycode). Other encodings or mixing UTF-8 and punycode likely result in incorrect return values. * or in ASCII/ACE (punycode) format. Other encodings or mixing UTF-8 and punycode likely result in incorrect return values.
*
* Use helper function psl_str_to_utf8lower() for normalization of @hostname and @cookie_domain.
* *
* Examples: * Examples:
* 1. Cookie domain 'example.com' would be acceptable for hostname 'www.example.com', * 1. Cookie domain 'example.com' would be acceptable for hostname 'www.example.com',
@ -1564,8 +1570,8 @@ int psl_is_cookie_domain_acceptable(const psl_ctx_t *psl, const char *hostname,
* @locale: locale of @str for to lowercase conversion, e.g. 'de' or %NULL * @locale: locale of @str for to lowercase conversion, e.g. 'de' or %NULL
* @lower: return value containing the converted string * @lower: return value containing the converted string
* *
* This helper function converts a string to lowercase UTF-8 representation. * This helper function converts a string to UTF-8 lowercase + NFCK representation.
* Lowercase UTF-8 is needed as input to the domain checking functions. * Lowercase + NFCK UTF-8 is needed as input to the domain checking functions.
* *
* @lower is set to %NULL on error. * @lower is set to %NULL on error.
* *