[asterisk-dev] Feedback requested for future 1.6 API documentation

[Tzafrir Cohen]

On Sun, Mar 01, 2009 at 11:47:17PM -0600, Jeff Peeler wrote:
> Last year in May I authored a document detailing all of the API 
> changes from 1.4 to 1.6.0 (doc/api-1.6.0-changes.odt). At that time 
> it was thought that we would be able to keep the API frozen for all 
> releases after 1.6.0. This rigid requirement has turned out to be too 
> hard to accommodate. The plan now is to continue documenting the API 
> changes from one release to the next. This decision poses a few 
> questions:
> 

> What format should be used? Both the file format and the content 
> layout should be considered. I originally chose an OpenDocument 
> text simply because it wasn't planned to ever be updated. I encourage 
> everybody to take a look at the existing document to get an idea of 
> what might should be included.

LaTeX example:


%%%%%%%%
%%%%%%%% Uglyness you shouldn't care about:
%%%%%%%%
\documentclass{article}
\newcommand{\old}{1.4}
\newcommand{\new}{1.6}
\newcommand{\oldexheader}{\subsection{\old\ Example}}
\newcommand{\newexheader}{\subsection{\new\ Example}}
% Maybe format as a table like in the ODF?
\newcommand{funcdiff}[6]{%
\section{#1}%
\paragraph*{Location}{\tt #2}%
\paragraph*{\old\ Prototype}{\tt #3}%
\paragraph*{\new\ Prototype}{\tt #4}%
\paragraph*{Change Explained}#5%
\paragraph*{New Types or Variables}#6%
}

\begin{document}

\tableofcontents

%%%%%%
%%%%%% The part that actually gets edited:
%%%%%%

\funcdiff{ast\_agi\_register}
  {/include/asterisk/agi.h}
  {int ast\_agi\_register(agi\_command *cmd);}
  {int ast\_agi\_register(struct ast\_module *mod, agi\_command *cmd);}
  {module parameter added to keep track which module registered the AGI %
    command as well as the reference count}
  {none}

No code examples required.

\funcdiff{ast\_aji\_send}
  {/include/asterisk/jabber.h}
  {int ast\_aji\_send(struct aji\_client *client, char *address, %
    char *message);}
  {int ast\_aji\_send\_chat(struct aji\_client *client, char *address, %
    char *message);}
  {function renamed for clarity}
  {none}

Note: a new ast\_aji\_send function is in 1.6.0

\oldexheader
\begin{verbatim}
tatic int manager\_jabber\_send( struct mansession *s, struct message *m ) 
{ 
    struct aji\_client *client = NULL; 
    char *id = astman\_get\_header(m,"ActionID"); 
    char *jabber = astman\_get\_header(m,"Jabber"); 
    char *screenname = astman\_get\_header(m,"ScreenName"); 
    char *message = astman\_get\_header(m,"Message"); 
    ...
    if (strchr(screenname, '@') && message){ 
-->     ast\_aji\_send(client, screenname, message); 
        if (!ast\_strlen\_zero(id)) 
            astman\_append(s, "ActionID: %s\r\n",id); 
        astman\_append(s, "Response: Success\r\n"); 
        return 0; 
    } 
    ...
\end{verbatim}

\newexheader
Exactly the same as above, except using the new function name:

\begin{verbatim}
-->     ast\_aji\_send\_chat(client, screenname, message); 
\end{verbatim}


\end{document}



So the problems we see:

* '_' (and '#'?) needs escaping
* Explicit verbatim envirnment around the examples. I can't think of a
  nice way to wrap this with macros.

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir