[pdf-devel] Re: [PATCH] Tokeniser API documentation

[jemarch]

Hi Michael.

   If the pdf_token_get_string_data/size functions are OK I'll add
   similar ones for the other token types.

They are ok in my opinion.

   address@hidden pdf_status_t pdf_tokeniser_reader_destroy 
(pdf_tokeniser_reader_t @var{reader})
   address@hidden pdf_status_t pdf_token_reader_destroy (pdf_tokeniser_reader_t 
@var{reader})

   address@hidden pdf_status_t pdf_tokeniser_writer_destroy 
(pdf_tokeniser_writer_t @var{writer})
   address@hidden pdf_status_t pdf_token_writer_destroy
   (pdf_tokeniser_writer_t @var{writer})

The types of the parameters are still using "pdf_tokeniser" instead
odf "pdf_token".

   address@hidden PDF_TOKEN_READABLE_STRINGS
   +Encode strings in a human-readable way
   +(i.e., in hexadecimal or with special characters escaped).

What are the semantics of this writing flag? Given that any string
contents can be expressed in hexadecimal, when will it use the
escaping of special characters? 

   address@hidden pdf_status_t pdf_token_keyword_new (const pdf_char_t 
address@hidden, pdf_size_t @var{size}, pdf_token_t address@hidden)
   +
   +Create a keyword token containing a copy of the given data.
   +
   address@hidden @strong
   address@hidden Parameters
   address@hidden @var
   address@hidden value
   +A pointer to the binary data that will make up the keyword.
   address@hidden size
   +The amount of data to copy, in octets.
   address@hidden token
   +A pointer to the newly created token.
   address@hidden table
   address@hidden Returns
   +A PDF status value:
   address@hidden @code
   address@hidden PDF_OK
   +The operation succeeded.
   address@hidden PDF_ENOMEM
   +Not enough memory.

Maybe would be good to add error checking on the contents of the
keyword. For example, it cannot start with /. To return PDF_EBADDATA
in that case may be appropriate. What do you think? The same would
apply to the other token_*_new functions.

Please include a ChangeLog entry in your patch. Also, please include a
patch to update AUTHORS with your contribution.

Thanks.

-- 
Jose E. Marchesi
address@hidden

GNU Project
http://www.gnu.org