Component Definition

What is a component?

In order to be better accustomed to faster development and to better leverage the module development, CooCox came up with the idea of "component development".

Then what is a component? To make it simple, a component mainly consists of 4 parts:

• Source code. It refers to reusable code, so we need to extract the variable part into component configuration.
• Document, including comments within the source code, component homepage, even user manual.
• Example (a project), to guarantee the ease of use of a component together with the document.
• Test (a project), to guarantee the quality of the component.

Catalogue

A component is a git repository. Its basic catalogue is like this:

E:.
└─components                                         
    └─ahnniu                                        
        └─hd44780 
            │.  gitignore
            │  cox.interface.lbr
            │  LCD_HD44780_Driver_Test.coproj
            │  README.md
            │  
            ├─assets
            │  ├─images
            │  │      hd44780_commands.gif
            │  │      hd44780_ddramaddress.gif
            │  │      ldc1.gif     
            │  │      
            │  └─pdf       
            │          
            ├─doxygen
            │  │  build.xml
            │  │  Doxyfile
            │  │  makefile
            │  │  
            │  ├─assets
            │  │  ├─images
            │  │  │  │  placeholder
            │  │  │  │  
            │  │  │  └─search
            │  │  │          mag_sel.png
            │  │  │          search_l.jpg
            │  │  │          search_m.jpg
            │  │  │          search_r.jpg
            │  │  │          
            │  │  ├─include
            │  │  │      footer.html
            │  │  │      header.html
            │  │  │      
            │  │  ├─javascripts
            │  │  │      resize.js
            │  │  │      
            │  │  └─stylesheets
            │  │      │  doxygen.css
            │  │      │  navtree.css
            │  │      │  style.css
            │  │      │  
            │  │      └─search
            │  │              search.css
            │  │              
            │  └─config
            │          layout.xml
            │          
            ├─helloworld
            │  └─putstring
            │          hd44780_config.h
            │          putstring.c
            │          README.md
            │          putstring.coproj
            │          
            ├─Output
            │  ├─doxygen
            │  │  │  doxygen.tag
            │  │  │  
            │  │  └─html            
            │  └─LCD_HD44780_Driver_Test
            │      ├─Debug
            │              
            ├─source
            │      hd44780.c
            │      hd44780.h
            │      hd44780_config.h.example
            │      hw_hd44780.h
            │      
            └─test
                    main.c
                    hd44780_config.h

• .gitignore contains files ignored by git repository
• README.md, a document based on markdown syntax, for creating the homepage of the component.
• assets, contains some images or PDF resources for users to add when needed
• doxygen, contains resources to auto-generate the document, the resources can be used directly with no extra modification.
• helloworld, a simple example of the component, including documents, code and projects.
• Output, the output path of projects and documents.
• source, source code of the component, uneditable after being added to the project.
• test, test code for the component.

Source code

Source code is the essential part of a component. For components with different functions and different sizes, the number of code lines can vary a lot, from just a few lines to thousands and millions of lines.

However, no matter how many lines there are, the code can be divided into these parts:

• Configuration
• UI
• Implementation

From the last section, we know that source code is uneditable after being added to the project, but the configuration must be set by users. Therefore, a component should have a configuration template, e.g.:hd44780_config.h.example. Users can copy the file to the application, rename it and modify the configuration.

Document

To make sure that the generated document is good-looking, we defined conventions for the component comments, mainly conventions of comments grouping. The group structure is like this:

HD44780
   ├─API reference
   ├─Enumeration
   ├─Hello World
   ├─Invoker Configuration
   ├─User Manual (optional)

The grouping can be implemented by Doxygen group command. The top-level group is usually the name of the component.

And then nest 4 groups in the top-level group:

• API reference
• Enumeration
• Hello World
• Invoker Configuration

Above are the names displayed in the output documents. Actually, you need to define the groups like this:

\addtogroup HD44780_Exported_APIs  API Reference
\addtogroup HD44780_Enum Enumeration

Use the unique symbol followed by the name to be displayed in the document.

Generally speaking,

• API reference and Enumeration groups are defined in the header files of user interface.
• Invoker Configuration group is defined in the configuration file
• Hello World group is defined in the example file.

The internal implementation of source code can further use grouping, or not. You can even use library files.