Leveraging Doxygen to Create Static Documentation for ObjectScript Classes

Effective documentation is a cornerstone of software development, aiding in code comprehension, maintenance, and collaboration. By harnessing the power of Doxygen and the ObjectScript filter I've created, you can generate rich static documentation from your source code. This approach does not require a running IRIS instance and thus is a good choice in situations when access to IRIS is not possible. Static documentation may be provided to end-users as-is, together with the source code.

Introduction

I searched through the community to find solutions targeting static documentation generation but couldn't find any exact matches. For example, this article comes close as they utilize XData blocks together with mkdocs to generate documentation, but a running IRIS instance is required. One shouldn't be forced to install IRIS to view the documentation. Instead, the single source of truth for source code should be Git, and the documentation should be generated from that source. This way, any authorized developer can clone the sources and generate up-to-date documentation for themselves with minimal effort.

In this article, we'll explore a solution that employs Doxygen and a Python filter I have written to automate documentation generation of ObjectScript code. This approach can significantly enhance the maintainability and collaboration of ObjectScript projects and promotes ease of use.

GitHub: Doxygen Filter for ObjectScript repository

Sample Documentation: GitHub Pages Documentation

Prerequisites

Before we delve into the details, ensure you have the following prerequisites in place:

• Python 3: Make sure Python 3 is installed on your system, as the filter script we'll discuss is written in Python.
• Doxygen: Download and install Doxygen, a popular documentation generation tool, from the official Doxygen website. Ensure that Doxygen's executable is accessible from your command line.

The Python Filter

To bridge the gap between ObjectScript and Doxygen, I've created a custom Python filter script that transforms the code into quasi-C++, making it suitable for Doxygen's C++ processor. Let's go through the steps to test the filter locally.

• Clone or Download the Repository: Begin by cloning or downloading the Doxygen Filter for ObjectScript repository to your local machine.
• Run the Filter Script: Open your terminal and navigate to the root of the repository. Execute the following command, replacing <input-file> with the path to your ObjectScript code file. Use the --debug flag to generate a separate output file for debugging purposes:

python doxyfilter_cache.py <input-file> [--debug]

The script will process your ObjectScript code and convert it into quasi-C++ code. If you use the --debug flag, the output will be saved in the ./output/ folder with the same name as your input file but with a .cpp extension. In other cases, the file is simply outputted to stdout.

Generating Documentation with Doxygen

To generate test documentation with Doxygen, simply run:

doxygen Doxyfile

In the root of the repository. The generated documentation will be available in the docs/html/ folder. Open index.html with your favorite browser and browse away!

Sample ObjectScript Code

Here's a sample ObjectScript code snippet that you can use as input for the filter script:

Class Sample.Person Extends %Persistent [ Abstract ]
{

Property Name As %String; // This is a sample property

Method GetName() As %String [ Private, Abstract ]
{
// Return the name
}

}

The filter will output the class into C++:

class Sample.Person : public %Persistent
{
public:

    virtual ~Person() = 0;

    %String Name; // This is a sample property

private:

    /// Note: this is an Abstract method
    virtual %String GetName()
    {
        /// Return the name
    }

}

By running the custom filter and Doxygen as described above, you can transform this ObjectScript code into structured, well-documented C++-like code and generate comprehensive documentation.

Conclusion

Creating comprehensive documentation for ObjectScript projects is vital for code maintainability and collaboration. By leveraging the power of Doxygen and a custom filter, you can automate the process of converting ObjectScript code into a format that Doxygen can understand and use for documentation generation.

It should be mentioned that this solution provides basic functionality for Doxygen to handle ObjectScript. Depending on your project's specific needs, you may need to extend or customize the filter script further. Nevertheless, this approach represents a step toward effective ObjectScript documentation generation with Doxygen.

Feel free to reach out if you have any questions or need further assistance in harnessing the power of Doxygen for your ObjectScript projects. If you have any suggestions to improve the filter, please create an issue on GitHub and/or create a Pull Request.