1.2. YCP File Header

1.2. YCP File Header
	Chapter 1. YCP Module and Client Documentation

The file header should show general information about the file name and location, author, and a general purpose.

Example 1.2. Exemplary file header

{
/**
 * File:	modules/CRONConfig.ycp
 * Package:	General YaST Modules
 * Authors:	John The Fish <john@thesmallfish.net>
 * Flags:	Stable
 *
 * $Id: $
 *
 * This module offers to read, change and write the current
 * CRON setup for all system users.
 */
 
    module "CRONConfig";
    ...
}

File header format:

Attribute: value

Possible Attributes are:

Authors
Author
Depends
File
Flags
Internal
Module
Package
Summary

1.2.1. `Authors` AKA `Author` Attribute

Defines the author(s) of the file.

Example 1.3. Single-line Authors tag

Authors: Wendy Graceful <grace@example.com>

Example 1.4. Multi-line Authors tag

Authors: Wendy Graceful <grace@example.com>
         Lars Kralewski <lars@example.com>

1.2.2. `Depends` Attribute

What does this file / module depend on.

Example 1.5. Depends tag

Depends: Language

1.2.3. `File` Attribute

Relative path where is this file located under the base YaST /usr/share/YaST2/ path.

Example 1.6. File tag

File: modules/HTTP.ycp

1.2.4. `Flags` Attribute

Defines the default value for the module stability (read: stability of module API).

Possible values are:

Stable
Unstable

Example 1.7. Flags tag

Flags: Stable

1.2.5. `Internal` Attribute

If a module is marked as Internal, it will be omitted while generation the YaST overall documentation. This tag is not mandatory, by default a module is not internal.

Example 1.8. Package tag

 *
 * Author: Joe Example <joe@example.com>
 * Internal
 *

1.2.6. `Package` AKA `Module` Attribute

Textual description of the package (YaST module) that this file belongs to. This tag is obsolete.

Example 1.9. Package tag

Package: SSHD Configuration Module

1.2.7. `Summary` Attribute

Defines the purpose of this file, such as what does do, how it does that, what it uses for that, etc.

Example 1.10. Multi-line Summary tag

Summary: This is a multiline summary for the exemplary YaST module
         that does nothing and has no valuable content at all.

Summary tag is something special —. You don't need to define the tag itself, just write a multiline text after at the bottom of the comment after the $Id: $ entry.

Example 1.11. Other Multi-line Summary tag

/**
 * File: modules/DoNothingAtAll.ycp
 *
 * ...
 *
 * $Id: $
 *
 * This is a multiline summary for the exemplary YaST module
 * that does nothing and has no valuable content at all.
 */


Chapter 1. YCP Module and Client Documentation		1.3. YCP Functions