APPENDIX A Common Examples

File Heading

/** @file
  Brief description of file’s purpose.

  Detailed description of file’s purpose.

  Copyright (c) 2006 - 2014, Acme Corporation. All rights reserved.<BR>
  This program and the accompanying materials
  are licensed and made available under the terms and conditions
  of the BSD License which accompanies this distribution. The full
  text of the license may be found at
  http://opensource.org/licenses/bsd-license.php

  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

  @par Specification Reference:
  - UEFI 2.3, Chapter 9, Device Path Protocol
  - PI 1.1, Chapter 10, Boot Paths
**/
#ifndef FOO_BAR_H_
#define FOO_BAR_H_

// Body of the file goes here

#endif // FOO_BAR_H_

Functioon Declarations

/** Brief description of this function's purpose.

  Follow it immediately with the detailed description.

  @param[in]       Arg1  Description of Arg1.
  @param[in]       Arg2  Description of Arg2 This is complicated and requires
                         multiple lines to describe.
  @param[out]      Arg3  Description of Arg3.
  @param[in, out]  Arg4  Description of Arg4.

  @retval  VAL_ONE  Description of what VAL_ONE signifies.
  @retval  OTHER    This is the only other return value. If there were other
                    return values, they would be listed.

**/
EFI_STATUS
EFIAPI
FooBar (
  IN     UINTN  Arg1,
  IN     UINTN  Arg2, OPTIONAL
     OUT UINTN  *Arg3,
  IN OUT UINTN  *Arg4
  );

Type Declarations

/// Brief description of this enum.
/// Detailed description if justified.
typedef enum {
  EnumMenberOne,  ///< First member description.
  EnumMemberTwo,  ///< Second member description.
  EnumMemberMax   ///< Number of members in this enum.
} ENUMERATE_TYPE;

/// Structure without forward reference.
typedef struct {
  UINT32                   Signature;  ///< Signature description.
  EFI_HANDLE               Handle;     ///< Handle description.
  EFI_PROD_PROT1_PROTOCOL  ProdProt1;  ///< ProdProt1 description.
  EFI_PROD_PROT2_PROTOCOL  ProdProt2;  ///< ProdProt2 description.
} DRIVER_NAME_INSTANCE;

/// Self referential Structure.
typedef struct EFI_CPU_IO_PROTO {
  struct EFI_CPU_IO_PROTO     *Mem;
  EFI_CPU_IO_PROTOCOL_ACCESS  Io;
} EFI_CPU_IO_PROTOCOL;

/// Forward reference
typedef struct StructTag MyStruct;

/// Forward reference target
struct StructTag {
  INT32 First;
  INT32 Second;
};

Function Calling

Status = TestString ();
Status = TestString (String, Index + 3, &Value);
Status = TestString (
           String,
           Index + 3,
           &Value
           );

Control Statements

if (Test && !Test2) {
  // This is an example comment to explain why this behavior
  // is appropriate.
  IamTheCode ();
} else if (Test2) {
  // This is an example comment to explain why this behavior
  // is appropriate.
  IamTheCode ();
} else {
  // This is an example comment to explain why this behavior
  // is appropriate.
  IamTheCode ();
}

while (TRUE) {
  IamTheCode ();
}

do {
  IamTheCode ();
} while (TRUE);

for (Index = 0; Index < MAX_INDEX; Index++) {
  IamTheCode (Index);
}

switch (Variable) {
case 1:
  IamTheCode ();
  break;

case 2:
  IamTheCode ();
  break;

default:
  IamTheCode ();
  break;
};