mRFC 0039: MidCOM Component Documentation requirements
Revision history
- 2008-12-03 Created by Marcin Sołtysiak
- 2008-12-23 Updated by Marcin Sołtysiak
- 2009-01-06 Updated by Marcin Sołtysiak
Background
This document describes Midgard rules for creating and maintaining required MidCOM Components Documentation.
Terminology
- help file - text file stored in 'documentation' folder in components skeleton. Help file follows the pattern {subject}.{lang}.txt, where {subject} is a brief keyword and {lang} id 2-char ISO language code. Some {subject}s can follow separate rules if required.
- subject - a keyword describing content of help item.
MidCOM Component Documentation Rules
- Component Documentation is required element that has to be in place before Component can be released officially along with any Midgard Release.
- Component Documentation is subject for approval before Release.
- Component Documentation help_files must be provided in as many languages as possible assuming English version is mandatory.
Component Documentation must cover the following areas:
- General Introduction briefly describing Component's purpose
- Style elements list and description, if applicable.
- Midgard Schema objects properties description included in mgdschema.xml file (English only), if applicable
- Routes brief and full descriptions, if applicable
- URL Methods - standalone scripts launched from exec component folder, if applicable
Component Documentation must be formatted using Markdown style
General Introduction
General introduction describes component purpose and should be brief but same time should explain the basic operations in a simple non-techie way. User oriented approach should be a main focus in that part of documentation. Introduction shall outline what input component expects, what tasks it does and what output it sends e.g.:
net.nehmer.blog is a newsticker or blog management component. It operates on midgard_article objects stored in midgard_topic container. Component
provides a variety of listing modes including RRS feeds. It also can read RSS from external sources.
Help topics
Each help_file stands for separate help topic. Upon list of help_files a Table of Contents is created on the fly and attached to Introduction page. Help topics are sorted alphabetically by help_file name therefore it is wise to prepend a filename with a number eg.
01_concept.en.txt
02_advanced_tasks.en.txt
Each help_file must begin with a help topic title that will be taken as subject for Table of Contents and navigation. It is advised that help topic title is formatted as Markdown Header 1 eg.:
My component help topic
---
Style elements list
Every Component that uses styling engine needs to provide a detailed instruction on every style element used. The instruction must contain usage guideliens along with available Component output data and some customization hints.
Article display index
<(index-start)> begins the article index, <(index-item)> displays an individual article and <(index-end)> ends the index. If there are no articles, <(index-empty)> is shown between <(index-start)> and <(index-end)> instead.
Style elements documentation must be midcom.admin.styleeditor compatible.
Midgard Schema objects properties description
Starting from version 8.9.3 MgdSchema provides node, a child to node in schema file. Component documentation must include descriptions for all relevant properties so that everyone knows what is the property storage type and purpose. It shall also tell about linkage to other MgdSchema classes.
<property name="relation" type="integer" index="yes">
<description>
Relation options:
- 10: Entry is made at location
- 20: Entry is about location
- 30: Entry is located at location
</description>
</property>
Handlers / URL Routes help
Components that can handle URL routes must provide help on all handlers. There should be a help file containing detailed help. Detailed part is also available from current view, floating toolbar 'Help' menu.
// Handle /list/random/<username|count>/
$this->_request_switch['photostream_list_random_count'] = array
(
'handler' => array ('org_routamc_photostream_handler_list', 'random'),
'fixed_args' => array('random'),
'variable_args' => 1,
);
For the handler above, Component must provide:
- 'handlers_{$handler_id}.lang.txt' file containing detailed description about controller operation and view provided by handler eg. file handlers_photostream_list_random_count.en.txt.
URL Methods
URL Methods are standalone scripts that live in exec component folder. URL Methods are launched by running /midcom-exec-{component}/{urlmethod}.php URL.
Documentation on URL Methods is generated in list form:
/midcom-exec-{component}/{urlmethod}.php
urlmethod_{urlmethod}
eg.
/midcom-exec-org.routamc.photostream/import_filesystem_folder.php
urlmethod_import_filesystem_folder
Localization database must contain urlmethod_{urlmethod} identifier and corresponding {urlmethod}.{lang}.txt must exist in documentation folder