Quantcast

Internal runtime documentation with Doxygen

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
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. :)



_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
Hey Jon/community,

This is now available as http://www.mono-project.com/api/ !

- Alex

On 07 Feb 2017, at 01:26, Jon Purdy via Mono-devel-list <[hidden email]> wrote:

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. :)


_______________________________________________
Mono-devel-list mailing list
[hidden email]
https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Flists.dot.net%2Fmailman%2Flistinfo%2Fmono-devel-list&data=02%7C01%7Calkpli%40microsoft.com%7C77cdfb982e4f4873750f08d44ef0030e%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636220240134940278&sdata=fb%2FERZWPidxzvuBONt3Pe91ZDgGtFqY2vUmV1jGXrag%3D&reserved=0


_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Oskar Berggren


2017-02-07 16:38 GMT+00:00 Alexander Köplinger via Mono-devel-list <[hidden email]>:
Hey Jon/community,

This is now available as http://www.mono-project.com/api/ !


Invalid certificate on that site.

/Oskar



_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
Hey Oskar,

Apologies, this is because we just switched the download server over to Azure CDN and the certificate provisioning on our custom domain takes longer than we expected.
It should be ready in a few hours, you can use https://mono-project.azureedge.net/api/master/ for now.

- Alex

On 07 Feb 2017, at 22:04, Oskar Berggren <[hidden email]> wrote:



2017-02-07 16:38 GMT+00:00 Alexander Köplinger via Mono-devel-list <[hidden email]>:
Hey Jon/community,

This is now available as http://www.mono-project.com/api/ !


Invalid certificate on that site.

/Oskar




_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Jonathan Mitchell
In reply to this post by Miguel de Icaza via Mono-devel-list
This is well overdue.
As an outsider I find getting my head around the runtime complex.
This will help a lot.

On 7 Feb 2017, at 00:26, Jon Purdy via Mono-devel-list <[hidden email]> wrote:

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. :)


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


_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
In reply to this post by Miguel de Icaza via Mono-devel-list

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 <[hidden email]> on behalf of Jon Purdy via Mono-devel-list <[hidden email]>
Sent: Monday, February 6, 2017 6:26:41 PM
To: [hidden email]
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. :)



_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
In reply to this post by Miguel de Icaza via Mono-devel-list

Hey Miguel,

 

Would it be an option to extend our tooling to understand doxygen’s format?

 

--

Rodrigo

 

From: Mono-devel-list <[hidden email]> on behalf of Miguel de Icaza via Mono-devel-list <[hidden email]>
Reply-To: Miguel de Icaza <[hidden email]>
Date: Monday, February 13, 2017 at 7:10 PM
To: Jon Purdy <[hidden email]>, "[hidden email]" <[hidden email]>
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 <[hidden email]> on behalf of Jon Purdy via Mono-devel-list <[hidden email]>
Sent: Monday, February 6, 2017 6:26:41 PM
To: [hidden email]
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. :)

 

 


_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list

Let us first explore the alternative.

 

I do like my format more than Doxygen’s default.

 

Miguel

 

From: Rodrigo Kumpera <[hidden email]>
Date: Tuesday, February 14, 2017 at 12:03 AM
To: Miguel de Icaza <[hidden email]>, Jon Purdy <[hidden email]>, "[hidden email]" <[hidden email]>
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 <[hidden email]> on behalf of Miguel de Icaza via Mono-devel-list <[hidden email]>
Reply-To: Miguel de Icaza <[hidden email]>
Date: Monday, February 13, 2017 at 7:10 PM
To: Jon Purdy <[hidden email]>, "[hidden email]" <[hidden email]>
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 <[hidden email]> on behalf of Jon Purdy via Mono-devel-list <[hidden email]>
Sent: Monday, February 6, 2017 6:26:41 PM
To: [hidden email]
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. :)

 

 


_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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
<[hidden email]> wrote:

> Let us first explore the alternative.
>
>
>
> I do like my format more than Doxygen’s default.
>
>
>
> Miguel
>
>
>
> From: Rodrigo Kumpera <[hidden email]>
> Date: Tuesday, February 14, 2017 at 12:03 AM
> To: Miguel de Icaza <[hidden email]>, Jon Purdy <[hidden email]>,
> "[hidden email]" <[hidden email]>
>
>
> 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 <[hidden email]> on behalf of
> Miguel de Icaza via Mono-devel-list <[hidden email]>
> Reply-To: Miguel de Icaza <[hidden email]>
> Date: Monday, February 13, 2017 at 7:10 PM
> To: Jon Purdy <[hidden email]>, "[hidden email]"
> <[hidden email]>
> 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 <[hidden email]> on behalf of
> Jon Purdy via Mono-devel-list <[hidden email]>
> Sent: Monday, February 6, 2017 6:26:41 PM
> To: [hidden email]
> 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
> [hidden email]
> http://lists.dot.net/mailman/listinfo/mono-devel-list
>



--
Studying for the Turing test
_______________________________________________
Mono-devel-list mailing list
[hidden email]
http://lists.dot.net/mailman/listinfo/mono-devel-list
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Internal runtime documentation with Doxygen

Miguel de Icaza via Mono-devel-list
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" <[hidden email]> 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
    <[hidden email]> wrote:
    > Let us first explore the alternative.
    >
    >
    >
    > I do like my format more than Doxygen’s default.
    >
    >
    >
    > Miguel
    >
    >
    >
    > From: Rodrigo Kumpera <[hidden email]>
    > Date: Tuesday, February 14, 2017 at 12:03 AM
    > To: Miguel de Icaza <[hidden email]>, Jon Purdy <[hidden email]>,
    > "[hidden email]" <[hidden email]>
    >
    >
    > 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 <[hidden email]> on behalf of
    > Miguel de Icaza via Mono-devel-list <[hidden email]>
    > Reply-To: Miguel de Icaza <[hidden email]>
    > Date: Monday, February 13, 2017 at 7:10 PM
    > To: Jon Purdy <[hidden email]>, "[hidden email]"
    > <[hidden email]>
    > 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 <[hidden email]> on behalf of
    > Jon Purdy via Mono-devel-list <[hidden email]>
    > Sent: Monday, February 6, 2017 6:26:41 PM
    > To: [hidden email]
    > 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
    > [hidden email]
    > 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
   

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