Resources - Considerations for Bigger Projects

Modules

Most source code project are organized in logical parts that are relatively independent from each other. Even though they are all contained in the same project - for instance an application - there is a logical separation in the source code.

Doc-O-Matic provides a convenient way of applying the same logical separation on the documentation using Modules. A module in Doc-O-Matic is defined by the source files it contains and by a topic that acts as container. A module generates its own separate Symbol Reference folders and Doc-O-Matic creates a class hierarchy for each module separately.

There are two different approaches on adding source files to a module

1. File-by-File
2. On a folder/file mask basis

Using the first approach gives you ultimate flexibility as each file is added to modules independently from all other files in the project. However, separation can be a very time-consuming task if there are many files to assign.

That is why Doc-O-Matic also provides a mechanism to add a folder/file mask combination to a module. All files matching a folder/file mask combination will be assigned to the corresponding file automatically. One other big advantage of this approach is that it's insensitive to changes in the project's file list.

There is a separate article about modules available here.

Splitting Projects

An alternative to using modules is completely splitting the source code into different Doc-O-Matic projects. This approach is useful when you have separate source code projects which depend on each other but are not interconnected.

A good example would be if you have a library that provides basic functionality (let's name it "Core") and other libraries or application that use that library (let's name it "App"). Core is independent from App so it could be documented independently.

One other reason to split a Doc-O-Matic project into multiple smaller projects is code and documentation size. Depending on the output format is may not be economical to put everything into one big project. Instead it might be more convenient to manage separate projects and build the output separately.

Project Databases

When Doc-O-Matic generates documentation it also generates a file for the project that contains information about it. This file is called Project Database and it consists of a link database and class information.

The link database stores link targets for the topics that have been exported to the documentation. This makes it possible to create inter-project links from one Doc-O-Matic to another.

In our example above, Doc-O-Matic would have generated a project database for Core. This database can be added to the "App" project and from that point on, Doc-O-Matic auto-links type names that App uses from Core because it knows there is a matching topic in Core's documentation.

Doc-O-Matic also uses the symbol information stored in the Project Database to resolve symbol names that can't be resolved locally. One example where Doc-O-Matic uses that information is the local class hierarchy Doc-O-Matic generates for all classes: If an ancestor class can't be resolved in the local project, Doc-O-Matic attempts to find it in the class information imported from other projects. That way Doc-O-Matic creates class hierarchies across project boundaries.