Documenting SAS File

DocItOut looks for certain comment block syntax. The information in these comment blocks will be added into the web documentation.

Please note that these syntax are optional. DocItOut will still generate the web documentation regardless of the syntax existence in the SAS file. However, it is highly recommended to include them in the SAS files to create a more useful web documentation.

File Header

/*!
 *      This file generates ten random numbers and doesn't do
 *      anything else special. I don't even know why this file is
 *      created.
 *
 *      @author         Choon-Chern Lim (Mike)
 *      @created        01/01/2026
 */

• Each SAS file can have only one comment block for the file header.
• This comment block begins with /*! and ends with */. It must be placed at the very top of the file.
• The file header captures three types of information:-
  • A description of the particular SAS file’s responsibilities.
  • The author of the file.
  • When the file is first created.
• This comment block has two tags: @author and @created.
• The order of the tags are important or they will be ignored.
• You can insert HTML tags into the description. For example, in the example below, I used <p> to begin a new paragraph and <b> to bold the word SAS. However, it is highly recommended to keep the HTML tag usage to the minimum.

/*!
 *      This file generates ten random numbers and doesn't do 
 *      anything else special. I don't even know why this file is 
 *      created.
 *      <p>
 *      This is the next paragraph. <b>SAS</b> is bold for some
 *      reason.
 *      </p>
 *
 *      @author         Choon-Chern Lim (Mike)
 *      @author         Popeye the Intern
 *      @author         Thundercat
 *      @created        01/01/2045
 */

• If you have more than one author, append more @author tags to the file header. I usually keep the primary author on the top rather than sorting them alphabetically.

Include Statement

/**
 *      Utility macros for generating the emails. Why? Because this
 *      is the coolest!
 */
%include "c:\project\pgm\utility.sas";

• This comment block does not have any tag.
• It begins with /** and ends with */. This comment block must be placed right above the %include statement.

Libname Statement

/**
 *      Data storage for Project MI350, which is physically stored in
 *      Windows 2003 environment.
 */
libname mylib "c:\project\data";

• This comment block does not have any tag.
• It begins with /** and ends with */. This comment block must be placed right above the libname statement.

Filename Statement

/**
 *      File storage for Project MI350, which is physically stored in
 *      Windows 2089 environment.
 */
filename myfile "c:\project\file";

• This comment block does not have any tag.
• It begins with /** and ends with */. This comment block must be placed right above the filename statement.

Macro Statement

/**
 *      Sends email to the intended recipient using 
 *      SMTP protocol. 
 */
%macro sendEmail;
... some implementation
%mend;

• The above comment block represents the simplest documentation for a macro.
• This comment block must be placed right above the macro statement.
• This comment block has two tags: @param and @return.
• The order of the tags are important or they will get ignored.

/**
 * Sends email to the intended recipient using
 * SMTP protocol.
 *
 * @param sender Sender's email address.
 */
%macro sendEmail(sender=myemail@sas.com);
	... some implementation
%mend;

• The above comment block consist of a @param tag that documents variable “sender”. The variable name listed in @param must match the variable name listed in the macro’s parameter. Otherwise, it will be ignored.

/**
 *      Sends email to the intended recipient using 
 *      SMTP protocol. 
 * 
 *      @param  sender          Sender's email address.
 *      @param  recipient       Recipient email address.
 *      @return Status "1" if successful, "0" otherwise.
 */
%macro sendEmail(sender=myemail@sas.com, recipient=);
	... some implementation
%mend;

• The above comment block consist of two @param tags and a @return tag.
• As mentioned earlier, the order of the tags are important. Otherwise, they will be ignored.