appendix_a_common_examples.md

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>
  SPDX-License-Identifier: BSD-2-Clause-Patent

  @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;
};