How to document further

Here is a brief overview of documentation project, doxygen tags and diagrams specification which were used to create this documentation.

I. Documentation solution and files.

The documentation is built not for the MapWinGIS source but for C# interop assemblies. It's possible to provide more friendly C# syntax in such way (rather then C++) and use the same solution to generate Visual Studio Intellisense file.

The solution consists of 3 projects:

The following switch is used to provide the desired names for documentation and Intellisense file.

 #if nsp
     namespace MapWinGIS {
 #if nsp
     public class IShapefile
     public class Shapefile

For documentation we shall get Shapefile, for Intellisense - MapWinGIS.IShapefile (nsp is defined in Project Build symbols)

The Doxygen setings are stored in the "MapWinGIS doxyfile" file in the root folder of the solution. Also there are several files that override default style settings: DoxygenLayout.xml, header.html, doxygen.css.

II. How to add new members.

To add the new members to the documentation after they were added to MapWinGIS it's necessary:

1. Rebuild Interop assemblies;
2. Add new members to the appropriate interface.

The most convenient way is to change the following line:

 public class IShapefile // or any other interface 

to the line:

 public class Shapefile: MapWinGIS.IShapefile 

Then to choose "Implement interface IShapefile" from the smart tag and to revert the changes back.

3. Add C# documentation comments and doxygen tags.
4. Generate the new html documentation by Doxygen.

To run Doxygen generation process:

The new documentation will be placed into "ouput" folder inside solution.

III. New Examples.

Some guidelines on how to add a new example on the Examples page.

1. Each new example must be placed in separate .cs file in "Examples\src" folder or its subfolders.

2. The file must add some public function to MapExamples partial class.

3. It should be registered in the application (see "Examples\Description.cs").

4. A file "examples_list.cs" with necessary definitions will be automatically generated in "Interop.MapWinGIS\Related pages\" folder on the running of the project.

5. It's possible to create a screenshot with the results of the example by clicking Snapshot button in the application. The screenshot will be added to the documentation automatically.

IV. Doxygen tags.

All the tags must be placed as C# comments (3 slashes) before the declaration of the member. The declaration of the Related pages and Examples can be placed in any part of the .cs files.

Here is list of useful Doxygen tags:

´╗┐1. Related pages:
\mainpage  <Page title>                   // only one for the project
\page     <page_name> <Page title> // can be placed in any .cs file
\section   <page_name> <Page title>       // for the page

2. Groups of API members:
\addtogroup <group_name> <Group title>    // to split the memebers of large classes into modules
                                   // in fact there is somewhat more than that, see the source

3. Classification of members:
\new48 <description>               // an alias created for \xrefitem command to mark new members
\deprecated <description>          // the deprecated members; will be added to the related page automatically

4. Reference:
\ref <the_member>                  // should be used in diagrams
\see <descripion>                  // "see also:" section will be added to the description of member
<a href = "url">                   // for external links

5. Commands to include external files:
\dotfile <filename>                // dot graph definition 
\example <filename>                // example to be placed in the Examples section of documentation
                                   // cross references will be added automatically for all members.
\image html <filename>                    // the image file to include; html keyword is mandatory
\include <filename>                // source file to be inlined in the description

6. Coammands to include inline code or diagram definitions:
\dot <diagram definition> \enddot  // dot graph definition
\code <code> \endcode                     // regular C# code

7. Formatting of text:
"-", "-#"                          // for unordered and ordered lists
"."                                // end the list
                                   // indentation can be used for nested lists
"\n"                               // new line
<table>, <div>, <b>                // regular html formatting

Doxygen manual

The path for external files (the files should be placed in either that or any nested folder):


Doxygen will automatically place links for the API members in case their full name is typed: AxMap. Use "%" sign to prevent this behavior: AxMap

Cross references in the examples are placed automatically as well. The only precondition - the correct declaration of variable type (either local or parameter). MapWinGIS namespace must not be used, i.e. Shapefile but not MapWinGIS.Shapefile.

V. Graphs definition.

Graphs a generated using Graphviz tool.

They can be either:

Graph definition consists of several parts:

The settings for nodes and edges can be:

Here is a small example to give the general idea about the structure. See details in the description of Dot tool in Graphviz documentation.

´╗┐digraph graph_name
    nodesep = 0.3;   // graph settings
    ranksep = 0.2;
    splines = ortho;
    // global settings for node
    node [shape= "polygon", peripheries = 2, color = lightblue, style = filled, height = 0.3, width = 1.0];
    // defininition of loads with some additional settings
    lb [ label="Chart" URL="\ref Chart"];

    // color, style, peripheries are overriden
    lbs [ label="Charts" URL="\ref Charts" color = gray, style = dashed, peripheries = 1];
    // edge global settings
    edge [ arrowhead="open", fontsize = 9, fontcolor = blue, color = "#606060", dir = "none" ]
    // definition of edge
    lbs -> lb [ URL="\ref Charts.get_Chart()"];

The output will be the following:


 All Classes Files Functions Enumerations Properties Events