extract-algorithm

C Code:

// -----------------------------------------------------------------
int multiply(int arg1, int arg2)
//<0> multiply(arg1, arg2)
//<0>
//<0> Multiply arg1 and arg2 as integers and return the result
{
//<1> if either argument is negative
if (arg1 < 0 || arg2 < 0)
  {
    //<2> print a warning, because we don't like negativity
    printf("arg1 or arg2 were negative\n");
    //<2> exit with return status 1
    exit(1);
  }

//<1> multiply the arguments
int return_value = arg1 * arg2;

//<1> return the result
return return_value;
}
// -----------------------------------------------------------------

with the command

extract-algorithm extract-algorithm.example1.xml extract-algorithm.example1.c

turns into:

C Code:

// -----------------------------------------------------------------
#define BIG_NUMBER 1000000
//<0> BIG_NUMBER(!)
//<0>
//<0> Big number is some big integer number, like a million or so.
//<0>
//<0> The (!) indicates a macro definition or some other entity 
//<0> that should have its own section and id to be able to link to, 
//<0> but which doesn't have a parameter list (the '(!)' part will 
//<0> be stripped in the doc)

void subtract_one(int *a)
//<0> subtract_one(a)
//<0>
//<0> Subtracts 1 from a
{
  *a = *a - 1;
}

void do_something(int *a, int *b)
//<0> do_something(a,
//<0>              b)
//<0>
//<0> Do some pointless manipulation of a and b.
//<0>
//<0> Second paragraph of function description which is created by 
//<0> leaving the empty comment line between the two paragraphs.
{
//<1> Check if a or b is negative by calling external function
//<1> is_negative(@).
//<1> The '@' means is_negative is function, but don't try to link it.
//<1> The '@' will be removed in the docs.
if (is_negative(a,b)) printf("is negative\n");
 
//<1> for each of the integers 0 through a
for (int i = 0; i <= *a; i++)
  {
    //<2> add b^i to a
    //<2> <footnote><para>this is a foonote</para></footnote>
    *a = *a + pow(b,i);

    //<2> if a is greater than <xref linkend="BIG_NUMBER"/>
    //<2> <footnote><para>
    //<2> BIG_NUMBER could also be automatically linked by using the
    //<2> syntax BIG_NUMBER(!).
    //<2> </para></footnote>
    if (*a > BIG_NUMBER)
      {
        //<3> report
        printf("a > %d\n", BIG_NUMBER);
        //<3> call subtract_one() to make a smaller
        subtract_one(a);

        //<3> also call the external function
        //<3> <ulink url="http://bobble.com/bobble.html#bobble_func">bobble_func
        //<3> </ulink>() with a link to its documentation on the web.
        bobble_func(a,b);
      }
}
// -----------------------------------------------------------------

with the command

extract-algorithm extract-algorithm.example2.xml extract-algorithm.example2.c

turns into: