Module Documentation

History

Table of Contents

• Module Documentation
• History
  • Table of Contents
• Overview
• Structure
• Reference Template

Overview

As part of the requirement in creating a code module, it must be documented.

This class creates a common framework for including documentation in a common way.

• Template Location - https://github.com/rdkcentral/hal-doxygen

Structure

The structure of repo of the surrounding module is expected to be :-

.
├── docs
│   ├── build                   -> [This repo]
│   │   ├── pages               -> [Common Markdown files to include]
│   └── template                -> [Reference template][(#reference_template)
│   ├── generate_docs.sh        -> module specific script to call ./build/Makefile [user defined]
│   ├── output                  -> Output Directory [Autogenerated]
│   └── pages                   -> User defined pages *.md search pattern applied from the doxygen configuration
│       ├── CONTRIBUTING.md -> ../../CONTRIBUTING.md    -> Link to page to include from top level .md extension required
│       ├── halspec.md                                  -> First Page in the documentation
│       ├── images                                      -> Contains images to include from the .md files
│       ├── LICENSE.md -> ../../LICENSE                 -> Link to page to include from top level .md extension required
│       └── NOTICE.md -> ../../NOTICE                   -> Link to page to include from top level .md extension required
├── include                                             -> Location of header files *.h search pattern applied from the doxygen configuration

• Note: pages .md is searched, as well as include/.h

Reference Template

Including in this repository in the template directory reference structure for the document directory.

This should be copied verbatim, then modifier as required for the specific component where HAL documentation is to be generated.

template
└── docs
    ├── generate_docs.sh
    └── pages
        ├── CONTRIBUTING.md -> ../../CONTRIBUTING.md
        ├── README.md -> ../../README.md
        ├── halSpec.md
        ├── images
        │   ├── sequence1.png
        │   ├── sequence_example.mmd
        │   ├── state1.png
        │   └── state_example.mmd
        ├── LICENSE.md -> ../../LICENSE
        └── NOTICE.md -> ../../NOTICE

The generate_docs.sh when ran will create this git repo under the build directory.