[Mono-dev] Internal runtime documentation with Doxygen

Tue Feb 14 16:05:10 UTC 2017

I spoke with Jon last night about the project.

We have two consumers with different needs.  

One set are the consumers of our embedding API, and for them we provide conceptual documentation that is augmented with the API description and is limited only to the API that we have agreed to support in the long term.   This is what our current internal documentation does.

Then we have the runtime developers that would like a tool to navigate the various internal data structures, methods and functions in the runtime, and are served by Doxygen and its current output.

We should certainly improve the documentation that Doxygen can extract from the runtime source code, but the documentation that needs to be extracted goes well beyond the very small API surface that the runtime has.   It goes to plenty of data structures and methods that are private and that we have historically not done much to document.

The question will be whether we will do this extra work to make this generally useful.   

In the meantime, we can certainly bootstrap some of the Doxygen comments by using the existing public API documentation, either by configuring Doxygen, or by doing the script solution that you proposed below.

Miguel.
On 2/14/17, 9:49 AM, "Greg Young" <gregoryyoung1 at gmail.com> wrote:

    I would imagine a quick script could be written to convert the tree
    into a temp directory with doxygen format to generate the docs from
    with relative ease. Running with a forked version of doxygen is likely
    a bad idea and I would be surprised if a pull request was accepted to
    support the other format.

    Maybe opening an issue on doxygen to see the likelyhood of a PR being
    accepted is a good starting point?

    On Tue, Feb 14, 2017 at 2:36 PM, Miguel de Icaza via Mono-devel-list
    <mono-devel-list at lists.dot.net> wrote:
    > Let us first explore the alternative.
    >
    >
    >
    > I do like my format more than Doxygen’s default.
    >
    >
    >
    > Miguel
    >
    >
    >
    > From: Rodrigo Kumpera <rokumper at microsoft.com>
    > Date: Tuesday, February 14, 2017 at 12:03 AM
    > To: Miguel de Icaza <miguel at microsoft.com>, Jon Purdy <jopur at microsoft.com>,
    > "mono-devel-list at lists.dot.net" <mono-devel-list at lists.dot.net>
    >
    >
    > Subject: Re: [Mono-dev] Internal runtime documentation with Doxygen
    >
    >
    >
    > Hey Miguel,
    >
    >
    >
    > Would it be an option to extend our tooling to understand doxygen’s format?
    >
    >
    >
    > --
    >
    > Rodrigo
    >
    >
    >
    > From: Mono-devel-list <mono-devel-list-bounces at lists.dot.net> on behalf of
    > Miguel de Icaza via Mono-devel-list <mono-devel-list at lists.dot.net>
    > Reply-To: Miguel de Icaza <miguel at microsoft.com>
    > Date: Monday, February 13, 2017 at 7:10 PM
    > To: Jon Purdy <jopur at microsoft.com>, "mono-devel-list at lists.dot.net"
    > <mono-devel-list at lists.dot.net>
    > Subject: Re: [Mono-dev] Internal runtime documentation with Doxygen
    >
    >
    >
    > Hello Jon,
    >
    >
    >
    > First, this is a great thing to do.
    >
    >
    >
    > I would not want to change the documentation strings in the source without
    > first trying to modify Doxygen to parse what we already have.
    >
    >
    >
    > While Doxygen can produce some schematics for internal documentation, we
    > would lose the already hand-written and organized documentation that we have
    > for various parts of the runtime.
    >
    >
    >
    > If it is not possible to modify Doxygen, let me suggest that we can have a
    > script parse the existing markup and modify into a separate tree, where you
    > can run Doxygen on.
    >
    >
    >
    > Miguel.
    >
    > ________________________________
    >
    > From: Mono-devel-list <mono-devel-list-bounces at lists.dot.net> on behalf of
    > Jon Purdy via Mono-devel-list <mono-devel-list at lists.dot.net>
    > Sent: Monday, February 6, 2017 6:26:41 PM
    > To: mono-devel-list at lists.dot.net
    > Subject: [Mono-dev] Internal runtime documentation with Doxygen
    >
    >
    >
    > We’ve recently added initial support for building Doxygen documentation[1].
    > The master docs are currently available on Jenkins[2]. We intend to set up a
    > central location online where these docs are deployed, as a convenient way
    > to browse the runtime code. My hope is that this helps new developers and
    > people unfamiliar with different parts of the runtime.
    >
    >
    >
    > But first, many comments need to be updated to use Doxygen syntax in order
    > to produce useful docs. It wouldn’t be very productive for me to do all of
    > this myself, so I propose that when we change some code, we make sure that
    > if the code is documented, then its documentation appears correctly in the
    > Doxygen output.
    >
    >
    >
    > I am not proposing that we write new documentation at this time, only verify
    > the docs we already have and get them ready for deployment.
    >
    >
    >
    > You can also build the docs locally with “make doxygen -C docs” in the Mono
    > repository, then open “docs/doxygen-output/index.html” to view the results.
    > (This can take several minutes.)
    >
    >
    >
    > Questions, comments, and objections are welcome. :)
    >
    >
    >
    > [1]: https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fmono%2Fmono%2Fpull%2F1383&data=02%7C01%7Cmiguel%40microsoft.com%7C9209d806f3b846f475da08d454e8b350%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636226805804897062&sdata=iAP5sYElZw%2FYMv2WcREcjifBbNHGyoKgUVcwKxlapHo%3D&reserved=0
    >
    > [2]: https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fjenkins.mono-project.com%2Fjob%2Ftest-mono-mainline-staticanalysis%2F&data=02%7C01%7Cmiguel%40microsoft.com%7C9209d806f3b846f475da08d454e8b350%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636226805804897062&sdata=jkg515Yo9nYPf%2FfjFySeGMu2gTc8BdC3ZQssdWcEcTk%3D&reserved=0
    >
    >
    >
    >
    > _______________________________________________
    > Mono-devel-list mailing list
    > Mono-devel-list at lists.dot.net
    > https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Flists.dot.net%2Fmailman%2Flistinfo%2Fmono-devel-list&data=02%7C01%7Cmiguel%40microsoft.com%7C9209d806f3b846f475da08d454e8b350%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636226805804897062&sdata=uBJvnr9znCMWZw4jEYkaE6VVrgSzpuDAL%2FtWfsTji0Q%3D&reserved=0
    >

    -- 
    Studying for the Turing test