[Mono-dev] Internal runtime documentation with Doxygen

[Greg Young]

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://github.com/mono/mono/pull/1383
>
> [2]: https://jenkins.mono-project.com/job/test-mono-mainline-staticanalysis/
>
>
>
>
> _______________________________________________
> Mono-devel-list mailing list
> Mono-devel-list at lists.dot.net
> http://lists.dot.net/mailman/listinfo/mono-devel-list
>



-- 
Studying for the Turing test