_idldoc: Automatic Documentation for CORBA IDL_
by Ernest J. Friedman-hill and Robert A. Whiteside

Example 1:

/** 
  The pressure of the system in atmospheres.
  @see PressurePsia
*/
readonly attribute double PressureAtm;


Listing One
/**
 * If mass is an input, then you may set it in grams with
 * this routine.
 * Legal values for the input string species name are:
 * Al, Fe, Ni, Co, Sc
 * <p>
 * Some of the following "@see" tags are illegal.  This is
 * intentional to make sure we don't do something embarassing
 * (like crash).  
 * @see GetGrams
 * @see grindle::GetGrams
 * @see grindle
 * @see GNDLX::enumMod
 * @see ::GNDLX::enumMod
 * @see GNDLX
 * @see GNDL
 * @raises genericException - if something goes wrong.
 * @see GNDL::grindle1
 * @see ::grindle::GetGrams
 * @see ::grindle::GetGrams (for more discussion)
 * @see ::grindle::GetGrams::
 * @raises specificException - if something else goes wrong.
 * @see 
 * @see SetMoles
 * @parm sz - The string selecting the desired species.
 * @parm lr - The new value for the number of moles
 */

void SetGrams(in string sz, in double lr)
  raises (genericException);


Listing Two
// These variables are used by the lexical analyzer to publish
// the most recently parsed doc comment
extern char idldoc_text[];
extern int idldoc_valid;

class be_node {
protected:
    char*   idldoc;
    char*   idldoc_tags;

   int fTagsParsed;

public:
    be_node(int snarf_idldoc=0);
    virtual void emit(EMT, ostream&);
    String idlDocString(UTL_Scope*, EMT);
    };

be_node::be_node(int snarf_idldoc) : idldoc(0),
                                     fTagsParsed(0),
                                     idldoc_tags(0)        
{
  if (snarf_idldoc)
    {
      if (idldoc_valid)
        {
          // don't let anyone else have this comment
          idldoc_valid = 0;
          idldoc = strdup(idldoc_text);

          /**
           * In case idldoc comments look like this,
           * remove whitespace-star-whitespace
           * sequences an the font of each line.
           */
          stripStars(idldoc);
          
          // Split the "tag" parts off from the idldoc string.
          idldoc_tags = splitTags(idldoc);
        }
    }
}


Listing Three
int wait_status;
switch (child_pid = fork()) {
case 0: /* Child - call cpp */
  /* Open the output file */
  int fd = open(tmp_file, O_WRONLY | O_CREAT | O_TRUNC, 0777);
  /* Attach this file to our standard output */
  dup2(fd, 1);
  /* Execute CPP with a predetermined set of arguments */
  /* A successful call to exec never returns */
  execvp(arglist[0], arglist);
  cout << "Failed to exec CPP!" << endl;
  exit(99);

default:    /* Parent - wait */
  /* Wait until this child process terminates */
  while (child_pid != wait(&wait_status));
  if (wait_status != 0) {
    cerr << "Preprocessor returned non-zero status." << endl;
    exit(99);
  }

} 
/* Preprocessing went OK; parent can now process output */


Listing Four
SECURITY_ATTRIBUTES saAttr; 
HANDLE hTmpFile;

/* Set the bInheritHandle flag so file handle is inherited. */ 
saAttr.nLength = sizeof(SECURITY_ATTRIBUTES); 
saAttr.bInheritHandle = TRUE; 
saAttr.lpSecurityDescriptor = NULL; 

/* 
 * The steps for redirecting child's STDOUT: 
 *     1.  Save current STDOUT, to be restored later. 
 *     2.  Create file to be STDOUT for child. 
 *     3.  Set STDOUT of parent to be the file, so 
 *         it is inherited by child. 
 */ 

/* Save the handle to the current STDOUT. */ 
HANDLE hSaveStdout = GetStdHandle(STD_OUTPUT_HANDLE); 

/* Create temp file for the child's STDOUT. */ 
hTmpFile = CreateFile(tmp_file, GENERIC_WRITE, 0, &saAttr,
            CREATE_NEW, FILE_ATTRIBUTE_NORMAL, 0);

/* Set a write handle to the file to be STDOUT. */ 
SetStdHandle(STD_OUTPUT_HANDLE, hTmpFile)

PROCESS_INFORMATION piProcInfo; 
STARTUPINFO siStartInfo; 

/* Set up members of STARTUPINFO and PROCESS_INFORMATION structures. */ 
memchr((void *) &piProcInfo, '\0', sizeof(PROCESS_INFORMATION));
memchr((void *) &siStartInfo, '\0', sizeof(STARTUPINFO));

siStartInfo.cb = sizeof(STARTUPINFO); 
siStartInfo.lpReserved = NULL; 
siStartInfo.lpReserved2 = NULL; 
siStartInfo.cbReserved2 = 0; 
siStartInfo.lpDesktop = NULL; 
siStartInfo.dwFlags = 0; 

/* Create the child process. */ 
if (!CreateProcess(NULL, 
      szCmdLine,     /* command line                       */ 
      NULL,          /* process security attributes        */ 
      NULL,          /* primary thread security attributes */ 
      TRUE,          /* handles are inherited              */ 
      0,             /* creation flags                     */ 
      NULL,          /* use parent's environment           */ 
      NULL,          /* use parent's current directory     */ 
      &siStartInfo,  /* STARTUPINFO pointer                */ 

     &piProcInfo)   /* receives PROCESS_INFORMATION       */ 
      )
  {
        cerr << "Couldn't run preprocessor." << endl;
  exit(99);
  }

DWORD stat = WaitForSingleObject(piProcInfo.hProcess, INFINITE);
GetExitCodeProcess(piProcInfo.hProcess, &stat);
if (stat != 0)
  {
  cerr << idl_global->prog_name() <<
      GTDEVEL(": Preprocessor returned non-zero status ") <<
      stat << "\n";
  exit(stat);
  }

CloseHandle(hTmpFile); 
/* Restore our old stdout */
SetStdHandle(STD_OUTPUT_HANDLE, hSaveStdout)



