From: Michael Sweet Date: Thu, 1 Jun 2017 02:22:40 +0000 (-0400) Subject: Documentation updates. X-Git-Tag: v2.2.4~56 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=53af7f21603aaf2100a8915e88329ff5d002a086;p=thirdparty%2Fcups.git Documentation updates. --- diff --git a/cups/Makefile b/cups/Makefile index e08af0a02f..bc022df30b 100644 --- a/cups/Makefile +++ b/cups/Makefile @@ -571,11 +571,12 @@ tlscheck: tlscheck.o $(LIBCUPSSTATIC) apihelp: echo Generating CUPS API help files... + $(RM) cupspm.xml mxmldoc --section "Programming" --body cupspm.md \ cupspm.xml \ - array.[ch] auth.c cups.h dest*.c dir.[ch] encode.c \ - file.[ch] http.h http*.c ipp.h ipp*.c language.[ch] \ - notify.c options.c pwg.h pwg-media.c tempfile.c \ + auth.c cups.h dest*.c encode.c \ + http.h http*.c ipp.h ipp*.c language.[ch] \ + notify.c options.c pwg.h pwg-media.c \ tls-darwin.c usersys.c util.c \ --coverimage cupspm.png \ --epub ../doc/help/cupspm.epub diff --git a/cups/auth.c b/cups/auth.c index 8348a2ccc0..c051c86ba8 100644 --- a/cups/auth.c +++ b/cups/auth.c @@ -54,7 +54,7 @@ extern const char *cssmErrorString(int error); # else # define GSS_AUTH_IDENTITY_TYPE_1 1 # define gss_acquire_cred_ex_f __ApplePrivate_gss_acquire_cred_ex_f -typedef struct gss_auth_identity +typedef struct gss_auth_identity /* @private@ */ { uint32_t type; uint32_t flags; diff --git a/cups/cups.h b/cups/cups.h index 16bd98fec1..f40306b045 100644 --- a/cups/cups.h +++ b/cups/cups.h @@ -308,11 +308,12 @@ typedef int (*cups_dest_cb_t)(void *user_data, unsigned flags, # ifdef __BLOCKS__ typedef int (^cups_dest_block_t)(unsigned flags, cups_dest_t *dest); /* Destination enumeration block - * @since CUPS 1.6/macOS 10.8@ */ + * @since CUPS 1.6/macOS 10.8@ + * @exclude all@ */ # endif /* __BLOCKS__ */ typedef const char *(*cups_password_cb_t)(const char *prompt); - /* Password callback */ + /* Password callback @exclude all@ */ typedef const char *(*cups_password_cb2_t)(const char *prompt, http_t *http, const char *method, diff --git a/cups/cupspm.md b/cups/cupspm.md index 97f2049d68..5bbce4b5ae 100644 --- a/cups/cupspm.md +++ b/cups/cupspm.md @@ -294,8 +294,8 @@ destination attributes: - "printer-state-reasons": Additional comma-delimited state keywords for the destination such as "media-tray-empty-error" and "toner-low-warning". - "printer-type": The `cups_ptype_t` value associated with the destination. -- "printer-uri": The URI associated with the destination; if not set, this - destination was discovered but is not yet setup as a local printer. +- "printer-uri-supported": The URI associated with the destination; if not set, + this destination was discovered but is not yet setup as a local printer. Use the `cupsGetOption` function to retrieve the value. For example, the following code gets the make and model of a destination: @@ -304,6 +304,7 @@ following code gets the make and model of a destination: dest->num_options, dest->options); + ## Detailed Destination Information Once a destination has been chosen, the `cupsCopyDestInfo` function can be used @@ -321,6 +322,7 @@ supported options and their supported, ready, and default values. It also can report constraints between different options and values, and recommend changes to resolve those constraints. + ### Getting Supported Options and Values The `cupsCheckDestSupported` function can be used to test whether a particular diff --git a/cups/dest.c b/cups/dest.c index 9493244c7c..9c256aa032 100644 --- a/cups/dest.c +++ b/cups/dest.c @@ -754,7 +754,7 @@ cupsConnectDest( * to by "cancel" is non-zero, or the callback function (or block) returns 0, * The caller is responsible for calling httpClose() on the returned object. * - * @since CUPS 1.6/macOS 10.8@ + * @since CUPS 1.6/macOS 10.8@ @exclude all@ */ http_t * /* O - Connection to server or @code NULL@ */ @@ -1360,7 +1360,7 @@ cupsEnumDests( * Enumeration happens on the current thread and does not return until all * destinations have been enumerated or the block returns 0. * - * @since CUPS 1.6/macOS 10.8@ + * @since CUPS 1.6/macOS 10.8@ @exclude all@ */ int /* O - 1 on success, 0 on failure */ @@ -1946,6 +1946,8 @@ _cupsGetDests(http_t *http, /* I - Connection to server or * * Use the @link cupsFreeDests@ function to free the destination list and * the @link cupsGetDest@ function to find a particular destination. + * + * @exclude all@ */ int /* O - Number of destinations */ @@ -1969,7 +1971,7 @@ cupsGetDests(cups_dest_t **dests) /* O - Destinations */ * Use the @link cupsFreeDests@ function to free the destination list and * the @link cupsGetDest@ function to find a particular destination. * - * @since CUPS 1.1.21/macOS 10.4@ + * @since CUPS 1.1.21/macOS 10.4@ @exclude all@ */ int /* O - Number of destinations */ @@ -3338,6 +3340,8 @@ cups_dnssd_local_cb( * Note: This function is needed because avahi_simple_poll_iterate is broken * and always uses a timeout of 0 (!) milliseconds. * (Avahi Ticket #364) + * + * @private@ */ static int /* O - Number of file descriptors matching */ diff --git a/cups/encode.c b/cups/encode.c index e60aec0d25..cf9ea8e88a 100644 --- a/cups/encode.c +++ b/cups/encode.c @@ -1,7 +1,7 @@ /* * Option encoding routines for CUPS. * - * Copyright 2007-2016 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2007 by Easy Software Products. * * These coded instructions, statements, and computer programs are the @@ -331,6 +331,8 @@ static int compare_ipp_options(_ipp_option_t *a, _ipp_option_t *b); * This function adds operation, job, and then subscription attributes, * in that order. Use the cupsEncodeOptions2() function to add attributes * for a single group. + * + * @exclude all@ */ void diff --git a/cups/http-addrlist.c b/cups/http-addrlist.c index 723bf029cd..22bd5a7d7f 100644 --- a/cups/http-addrlist.c +++ b/cups/http-addrlist.c @@ -1,7 +1,7 @@ /* * HTTP address list routines for CUPS. * - * Copyright 2007-2016 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2007 by Easy Software Products, all rights reserved. * * These coded instructions, statements, and computer programs are the @@ -32,7 +32,7 @@ /* * 'httpAddrConnect()' - Connect to any of the addresses in the list. * - * @since CUPS 1.2/macOS 10.5@ + * @since CUPS 1.2/macOS 10.5@ @exclude all@ */ http_addrlist_t * /* O - Connected address or NULL on failure */ diff --git a/cups/http-support.c b/cups/http-support.c index 1ca01b27e1..3ab461e144 100644 --- a/cups/http-support.c +++ b/cups/http-support.c @@ -1,7 +1,7 @@ /* * HTTP support routines for CUPS. * - * Copyright 2007-2016 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2007 by Easy Software Products, all rights reserved. * * These coded instructions, statements, and computer programs are the @@ -543,7 +543,7 @@ httpAssembleUUID(const char *server, /* I - Server name */ * This function is deprecated. Use the httpDecode64_2() function instead * which provides buffer length arguments. * - * @deprecated@ + * @deprecated@ @exclude all@ */ char * /* O - Decoded string */ @@ -671,7 +671,7 @@ httpDecode64_2(char *out, /* I - String to write to */ * This function is deprecated. Use the httpEncode64_2() function instead * which provides buffer length arguments. * - * @deprecated@ + * @deprecated@ @exclude all@ */ char * /* O - Encoded string */ @@ -778,7 +778,7 @@ httpEncode64_2(char *out, /* I - String to write to */ /* * 'httpGetDateString()' - Get a formatted date/time string from a time value. * - * @deprecated@ + * @deprecated@ @exclude all@ */ const char * /* O - Date/time string */ @@ -888,7 +888,7 @@ httpGetDateTime(const char *s) /* I - Date/time string */ * * This function is deprecated; use the httpSeparateURI() function instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ void @@ -912,7 +912,7 @@ httpSeparate(const char *uri, /* I - Universal Resource Identifier */ * This function is deprecated; use the httpSeparateURI() function instead. * * @since CUPS 1.1.21/macOS 10.4@ - * @deprecated@ + * @deprecated@ @exclude all@ */ void @@ -2310,6 +2310,8 @@ http_resolve_cb( * Note: This function is needed because avahi_simple_poll_iterate is broken * and always uses a timeout of 0 (!) milliseconds. * (Avahi Ticket #364) + * + * @private@ */ static int /* O - Number of file descriptors matching */ diff --git a/cups/http.c b/cups/http.c index 7925513adb..15004b6241 100644 --- a/cups/http.c +++ b/cups/http.c @@ -1,7 +1,7 @@ /* * HTTP routines for CUPS. * - * Copyright 2007-2015 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2007 by Easy Software Products, all rights reserved. * * This file contains Kerberos support code, copyright 2006 by @@ -417,7 +417,7 @@ httpCompareCredentials( * * This function is deprecated - use @link httpConnect2@ instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ http_t * /* O - New HTTP connection */ @@ -482,7 +482,7 @@ httpConnect2( * This function is now deprecated. Please use the @link httpConnect2@ function * instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ http_t * /* O - New HTTP connection */ @@ -1006,7 +1006,7 @@ httpGetKeepAlive(http_t *http) /* I - HTTP connection */ * This function is deprecated and will not return lengths larger than * 2^31 - 1; use httpGetLength2() instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - Content length */ @@ -1346,7 +1346,7 @@ httpGetStatus(http_t *http) /* I - HTTP connection */ /* * 'httpGetSubField()' - Get a sub-field value. * - * @deprecated@ + * @deprecated@ @exclude all@ */ char * /* O - Value or NULL */ @@ -1939,7 +1939,7 @@ httpPut(http_t *http, /* I - HTTP connection */ * This function is deprecated. Use the httpRead2() function which can * read more than 2GB of data. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - Number of bytes read */ @@ -2326,7 +2326,7 @@ httpReadRequest(http_t *http, /* I - HTTP connection */ * This function is deprecated. Please use the @link httpReconnect2@ function * instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - 0 on success, non-zero on failure */ @@ -3259,7 +3259,7 @@ httpWait(http_t *http, /* I - HTTP connection */ * This function is deprecated. Use the httpWrite2() function which can * write more than 2GB of data. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - Number of bytes written */ diff --git a/cups/tls-darwin.c b/cups/tls-darwin.c index b6e88b01e3..30b1e86de8 100644 --- a/cups/tls-darwin.c +++ b/cups/tls-darwin.c @@ -21,7 +21,7 @@ #include -extern char **environ; +extern char **environ; /* @private@ */ /* diff --git a/cups/usersys.c b/cups/usersys.c index 333d21e00d..b4fa81f789 100644 --- a/cups/usersys.c +++ b/cups/usersys.c @@ -1,7 +1,7 @@ /* * User, system, and password routines for CUPS. * - * Copyright 2007-2015 by Apple Inc. + * Copyright 2007-2017 by Apple Inc. * Copyright 1997-2006 by Easy Software Products. * * These coded instructions, statements, and computer programs are the @@ -132,6 +132,8 @@ cupsEncryption(void) * thread in a program. Multi-threaded programs that override the setting via * the @link cupsSetPasswordCB@ or @link cupsSetPasswordCB2@ functions need to * do so in each thread for the same function to be used. + * + * @exclude all@ */ const char * /* O - Password */ @@ -297,6 +299,8 @@ cupsSetEncryption(http_encryption_t e) /* I - New encryption preference */ * Note: The current password callback is tracked separately for each thread * in a program. Multi-threaded programs that override the callback need to do * so in each thread for the same callback to be used. + * + * @exclude all@ */ void diff --git a/cups/util.c b/cups/util.c index 28ebbd0b0b..c7163c2e09 100644 --- a/cups/util.c +++ b/cups/util.c @@ -48,6 +48,8 @@ static int cups_create_cb(_cups_createdata_t *data, unsigned flags, cups_dest_t * * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get * the cause of any failure. + * + * @exclude all@ */ int /* O - 1 on success, 0 on failure */ @@ -71,7 +73,7 @@ cupsCancelJob(const char *name, /* I - Name of printer or class */ * Use the @link cupsLastError@ and @link cupsLastErrorString@ functions to get * the cause of any failure. * - * @since CUPS 1.4/macOS 10.6@ + * @since CUPS 1.4/macOS 10.6@ @exclude all@ */ ipp_status_t /* O - IPP status */ @@ -159,7 +161,7 @@ cupsCancelJob2(http_t *http, /* I - Connection to server or @code CUPS_HTTP_ * print, use the @link cupsPrintFile2@ or @link cupsPrintFiles2@ function * instead. * - * @since CUPS 1.4/macOS 10.6@ + * @since CUPS 1.4/macOS 10.6@ @exclude all@ */ int /* O - Job ID or 0 on error */ @@ -238,7 +240,7 @@ cupsCreateJob( * * The document must have been started using @link cupsStartDocument@. * - * @since CUPS 1.4/macOS 10.6@ + * @since CUPS 1.4/macOS 10.6@ @exclude all@ */ ipp_status_t /* O - Status of document submission */ @@ -289,7 +291,7 @@ cupsFreeJobs(int num_jobs, /* I - Number of jobs */ * This function is deprecated and no longer returns a list of printer * classes - use @link cupsGetDests@ instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - Number of classes */ @@ -311,6 +313,8 @@ cupsGetClasses(char ***classes) /* O - Classes */ * Applications should use the @link cupsGetDests@ and @link cupsGetDest@ * functions to get the user-defined default printer, as this function does * not support the lpoptions-defined default printer. + * + * @exclude all@ */ const char * /* O - Default printer or @code NULL@ */ @@ -334,7 +338,7 @@ cupsGetDefault(void) * functions to get the user-defined default printer, as this function does * not support the lpoptions-defined default printer. * - * @since CUPS 1.1.21/macOS 10.4@ + * @since CUPS 1.1.21/macOS 10.4@ @exclude all@ */ const char * /* O - Default printer or @code NULL@ */ @@ -400,6 +404,8 @@ cupsGetDefault2(http_t *http) /* I - Connection to server or @code CUPS_HTTP_DE * of state, while @code CUPS_WHICHJOBS_ACTIVE@ returns jobs that are * pending, processing, or held and @code CUPS_WHICHJOBS_COMPLETED@ returns * jobs that are stopped, canceled, aborted, or completed. + * + * @exclude all@ */ int /* O - Number of jobs */ @@ -695,7 +701,7 @@ cupsGetJobs2(http_t *http, /* I - Connection to server or @code CUPS_HTTP_D * This function is deprecated and no longer returns a list of printers - use * @link cupsGetDests@ instead. * - * @deprecated@ + * @deprecated@ @exclude all@ */ int /* O - Number of printers */ @@ -710,6 +716,8 @@ cupsGetPrinters(char ***printers) /* O - Printers */ /* * 'cupsPrintFile()' - Print a file to a printer or class on the default server. + * + * @exclude all@ */ int /* O - Job ID or 0 on error */ @@ -730,7 +738,7 @@ cupsPrintFile(const char *name, /* I - Destination name */ * 'cupsPrintFile2()' - Print a file to a printer or class on the specified * server. * - * @since CUPS 1.1.21/macOS 10.4@ + * @since CUPS 1.1.21/macOS 10.4@ @exclude all@ */ int /* O - Job ID or 0 on error */ @@ -752,6 +760,8 @@ cupsPrintFile2( /* * 'cupsPrintFiles()' - Print one or more files to a printer or class on the * default server. + * + * @exclude all@ */ int /* O - Job ID or 0 on error */ @@ -778,7 +788,7 @@ cupsPrintFiles( * 'cupsPrintFiles2()' - Print one or more files to a printer or class on the * specified server. * - * @since CUPS 1.1.21/macOS 10.4@ + * @since CUPS 1.1.21/macOS 10.4@ @exclude all@ */ int /* O - Job ID or 0 on error */ @@ -908,7 +918,7 @@ cupsPrintFiles2( * @code CUPS_FORMAT_TEXT@ are provided for the "format" argument, although * any supported MIME type string can be supplied. * - * @since CUPS 1.4/macOS 10.6@ + * @since CUPS 1.4/macOS 10.6@ @exclude all@ */ http_status_t /* O - HTTP status of request */ diff --git a/doc/help/api-filter.html b/doc/help/api-filter.html index 0880e9272b..7614f69618 100644 --- a/doc/help/api-filter.html +++ b/doc/help/api-filter.html @@ -1388,8 +1388,8 @@ variable or the device URI passed in argv[0], whichever is found first.

-

 CUPS 1.4/macOS 10.6 cupsBackendReport

-

Write a device line from a backend.

+

cupsBackendReport

+

PPD attribute

void cupsBackendReport (
    const char *device_scheme,
@@ -1414,7 +1414,8 @@ void cupsBackendReport (

device_location
device-location string or NULL
-

Discussion

+

Return Value

+

Write a device line from a backend.

This function writes a single device line to stdout for a backend. It handles quoting of special characters in the device-make-and-model, device-info, device-id, and device-location strings. diff --git a/doc/help/api-ppd.html b/doc/help/api-ppd.html index 25709415df..b3181369e2 100644 --- a/doc/help/api-ppd.html +++ b/doc/help/api-ppd.html @@ -1438,7 +1438,7 @@ name can be found, NULL is returned.

ppdMarkDefaults

-

Mark all default options in the PPD file.

+

Choice pointer

void ppdMarkDefaults (
    ppd_file_t *ppd
@@ -1448,6 +1448,8 @@ void ppdMarkDefaults (

ppd
PPD file record
+

Return Value

+

Mark all default options in the PPD file.

ppdMarkOption

Mark an option in a PPD file and return the number of conflicts.

diff --git a/doc/help/api-raster.html b/doc/help/api-raster.html index 951dab6010..54b88d1dc8 100644 --- a/doc/help/api-raster.html +++ b/doc/help/api-raster.html @@ -8,6 +8,7 @@ +