Re: 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 <[email protected]> on behalf of Miguel de Icaza via Mono-devel-list <[email protected]>
Reply-To: Miguel de Icaza <[email protected]>
Date: Monday, February 13, 2017 at 7:10 PM
To: Jon Purdy <[email protected]>, "[email protected]" <[email protected]>
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 <[email protected]> on behalf of Jon Purdy via Mono-devel-list <[email protected]>
Sent: Monday, February 6, 2017 6:26:41 PM
To: [email protected]
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://github.com/mono/mono/pull/1383<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fmono%2Fmono%2Fpull%2F1383&data=02%7C01%7Cmiguel%40microsoft.com%7Cf96c0eeb36f14d1c643108d44ef00252%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636220240129107362&sdata=W8CTB7Yzn4rO8GorGtx18m15d7CjxwmUnx3W%2BhDcnQo%3D&reserved=0>
[2]: https://jenkins.mono-project.com/job/test-mono-mainline-staticanalysis<https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fjenkins.mono-project.com%2Fjob%2Ftest-mono-mainline-staticanalysis&data=02%7C01%7Cmiguel%40microsoft.com%7Cf96c0eeb36f14d1c643108d44ef00252%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636220240129107362&sdata=lu0jqyy5pAiIn2eNmFnt8VKQLet1eIaV5OeamRPhMSM%3D&reserved=0>/

_______________________________________________
Mono-devel-list mailing list
[email protected]
http://lists.dot.net/mailman/listinfo/mono-devel-list