Re: Feature request: generate documentation from C files

[Simon Josefsson]

address@hidden (Karl Berry) writes:

> Hi Simon,
>
>     Would a tool to extract GTK-DOC comments and create Texinfo source be
>     suitable for inclusion in texinfo?  What do you think of the approach?
>     Is it a bad idea altogether?
>
> I think it is a very nice idea, and I'd be happy to include such a
> script in Texinfo.  Although it seems like a toss-up as to whether it is
> better to include it in Texinfo or in GTK.

For purely egoistic reasons, I'd prefer to have it in texinfo, since
texinfo is much more likely to be installed on the machines I use,
compared to the GTK-DOC-tool package that have a large dependency on
various SGML and XML packages.  But I agree it doesn't matter.  Could
even be a standalone package.

(Frankly, I have never been able to install GTK-DOC-tools manually,
they always complain about a missing XML catalog file and various
other SGMLy things, so I'm relying on the Debian package.)

> I'm cc-ing Alper Ersoy, who's done a lot of work with Texinfo and GTK,
> to get his reaction and advice.  (Alper, I'll send you Simon's original
> message separately.)

I have one question: has there been some thought/work on expressing
more markup within the comments?  For GSSLib, I would like to copy the
RFC 2744 description of functions, and they can contain example code
and text paragraph of different indention levels.  One example below.

Thanks.

5.19. gss_init_sec_context

   OM_uint32 gss_init_sec_context (
     OM_uint32                    *minor_status,
     const gss_cred_id_t          initiator_cred_handle,
     gss_ctx_id_t                 *context_handle,\
     const gss_name_t             target_name,
     const gss_OID                mech_type,
     OM_uint32                    req_flags,
     OM_uint32                    time_req,
     const gss_channel_bindings_t input_chan_bindings,
     const gss_buffer_t           input_token
     gss_OID                      *actual_mech_type,
     gss_buffer_t                 output_token,
     OM_uint32                    *ret_flags,
     OM_uint32                    *time_rec )

   Purpose:

   Initiates the establishment of a security context between the
   application and a remote peer.  Initially, the input_token parameter
   should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
   gss_buffer_desc object whose length field contains the value zero.
   The routine may return a output_token which should be transferred to
   the peer application, where the peer application will present it to
   gss_accept_sec_context.  If no token need be sent,
   gss_init_sec_context will indicate this by setting the length field
   of the output_token argument to zero. To complete the context
   establishment, one or more reply tokens may be required from the peer
   application; if so, gss_init_sec_context will return a status
   containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
   In this case, gss_init_sec_context should be called again when the
   reply token is received from the peer application, passing the reply
   token to gss_init_sec_context via the input_token parameters.

   Portable applications should be constructed to use the token length
   and return status to determine whether a token needs to be sent or
   waited for.  Thus a typical portable caller should always invoke
   gss_init_sec_context within a loop:

   int context_established = 0;
   gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
          ...
   input_token->length = 0;

   while (!context_established) {
     maj_stat = gss_init_sec_context(&min_stat,
                                     cred_hdl,
                                     &context_hdl,
                                     target_name,
                                     desired_mech,
                                     desired_services,
                                     desired_time,
                                     input_bindings,
                                     input_token,
                                     &actual_mech,
                                     output_token,
                                     &actual_services,
                                     &actual_time);
     if (GSS_ERROR(maj_stat)) {
       report_error(maj_stat, min_stat);
     };

     if (output_token->length != 0) {
       send_token_to_peer(output_token);
       gss_release_buffer(&min_stat, output_token)
     };
     if (GSS_ERROR(maj_stat)) {

       if (context_hdl != GSS_C_NO_CONTEXT)
         gss_delete_sec_context(&min_stat,
                                &context_hdl,
                                GSS_C_NO_BUFFER);
       break;
     };

     if (maj_stat & GSS_S_CONTINUE_NEEDED) {
       receive_token_from_peer(input_token);
     } else {
       context_established = 1;
     };
   };

   Whenever the routine returns a major status that includes the value
   GSS_S_CONTINUE_NEEDED, the context is not fully established and the
   following restrictions apply to the output parameters:

      The value returned via the time_rec parameter is undefined Unless
      the accompanying ret_flags parameter contains the bit
      GSS_C_PROT_READY_FLAG, indicating that per-message services may be
      applied in advance of a successful completion status, the value
      returned via the actual_mech_type parameter is undefined until the
      routine returns a major status value of GSS_S_COMPLETE.
...