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:

• Interop.MapWinGIS (holds definitions of COM interfaces);
• AxInterop.MapWinGIS (holds definition of AxMap control);
• Examples (the files with C# examples and small WinForms application to test them).

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

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


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.

4. Generate the new html documentation by Doxygen.

To run Doxygen generation process:

• run Doxywizard.exe;
• open the file "MapWinGIS doxyfile" in the root folder of the solution;
• click "Run doxygen" button on the "Run" tab.

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
<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):

 Resources\graphs\
Resources\images\
Examples\src\


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:

• inlined in code between \dot \enddot commands;
• defined in external file.

Graph definition consists of several parts:

• general settings;
• node settings;
• list of nodes;
• edges settings;
• list of edges.

The settings for nodes and edges can be:

• global (node and edge tags) which are used for all the following lines;
• local which are used for a single node or edge and override global settings.

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];

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: