The recent conversion of the D compiler source code opens up the practicality of using Ddoc on the code. Like the Phobos Ddoc output is browsable on dlang.org, the D compiler source should be, too. It also provides an incentive to properly document the compiler source code, and improve tools that use Ddoc to cross reference and otherwise analyze D source code.

Anyone want to take this on? It shouldn't be hard, pretty much just copy what is done to make the Phobos docs online.

On 1/7/16 9:32 AM, Walter Bright wrote:
> The recent conversion of the D compiler source code opens up the
> practicality of using Ddoc on the code. Like the Phobos Ddoc output is
> browsable on dlang.org, the D compiler source should be, too. It also
> provides an incentive to properly document the compiler source code, and
> improve tools that use Ddoc to cross reference and otherwise analyze D
> source code.
>
> Anyone want to take this on? It shouldn't be hard, pretty much just copy
> what is done to make the Phobos docs online.

This is a fantastic idea! -- Andrei

On 2016-01-07 15:32, Walter Bright wrote:
> The recent conversion of the D compiler source code opens up the
> practicality of using Ddoc on the code. Like the Phobos Ddoc output is
> browsable on dlang.org, the D compiler source should be, too. It also
> provides an incentive to properly document the compiler source code, and
> improve tools that use Ddoc to cross reference and otherwise analyze D
> source code.
>
> Anyone want to take this on? It shouldn't be hard, pretty much just copy
> what is done to make the Phobos docs online.

The hard part is do documented it with proper Ddoc.

-- 
/Jacob Carlborg

On 1/7/2016 7:52 AM, Jacob Carlborg wrote:
> The hard part is do documented it with proper Ddoc.

I know. But as I mentioned, there is no incentive to do this unless there is Ddoc output. Chicken and egg. I suggest we do the easy part and lay the egg (!) and get moving on it.

On Thursday, 7 January 2016 at 14:32:32 UTC, Walter Bright wrote:
> The recent conversion of the D compiler source code opens up the practicality of using Ddoc on the code.

There's been nothing stopping people from commenting dmd's source in the past, but it barely has any.

I guess anything to encourage more would be good. Though I think it is VERY important to comment on the why in implementation.

Knowing what things do is nice, and we could use some comments (especially on the module level!), but that basically makes sense once you get into it and there's a wiki article to help you get started.

The why can be extremely hard to figure out looking at the code alone though.

On 1/7/2016 9:21 AM, Adam D. Ruppe wrote:
> On Thursday, 7 January 2016 at 14:32:32 UTC, Walter Bright wrote:
>> The recent conversion of the D compiler source code opens up the practicality
>> of using Ddoc on the code.
>
> There's been nothing stopping people from commenting dmd's source in the past,
> but it barely has any.

Consider the state of Phobos docs before Ddoc. It was as badly documented as dmd source code is, or even worse. Ddoc revolutionized that. Putting the Ddoc results online produces quick feedback on improving the comments, hence is motivating.

On Thursday, 7 January 2016 at 18:46:35 UTC, Walter Bright wrote:
> On 1/7/2016 9:21 AM, Adam D. Ruppe wrote:
>> On Thursday, 7 January 2016 at 14:32:32 UTC, Walter Bright wrote:
>>> The recent conversion of the D compiler source code opens up the practicality
>>> of using Ddoc on the code.
>>
>> There's been nothing stopping people from commenting dmd's source in the past,
>> but it barely has any.
>
> Consider the state of Phobos docs before Ddoc. It was as badly documented as dmd source code is, or even worse. Ddoc revolutionized that. Putting the Ddoc results online produces quick feedback on improving the comments, hence is motivating.

Walter, I think that this is an important direction for improvement of DMD and I would like to help. How do you envision this to work:

=====

A) Local http server that you can start like so:
cd dmd
make serve-dmd-docs
browser 127.0.0.1:8080/dmd-internal-docs

B) Docs on dlang.org updated with every merged PR:
dlang.org/dmd-internal-docs (dmd stable branch)
dlang.org/dmd-internal-docs-prerelease (dmd master branch)

In addition to:
dlang.org/spec
dlang.org/phobos
dlang.org/phobos-prerelease

C) Something else?

=====

I suggest we start with option A) and later implement B).
A) should be relatively easy to implement with DDOX and later we can extend
dlang.org/library to dlang.org/dmd-prerelease.

How does this sound?

On 01/07/2016 03:18 PM, ZombineDev wrote:
> I suggest we start with option A) and later implement B).

That sounds fine. In the long run, building the site would build the dmd docs the same way today it's building druntime and phobos docs. Thanks for your consideration! -- Andrei

On 2016-01-07 21:18, ZombineDev wrote:

> A) Local http server that you can start like so:
> cd dmd
> make serve-dmd-docs
> browser 127.0.0.1:8080/dmd-internal-docs

What would be the point of the web server? Talk about adding complexity and dependencies. It's enough to generate the HTML, CSS and JavaScript. Then just open the files in your browser. Not need to have a web server running.

-- 
/Jacob Carlborg

On 1/7/2016 11:54 PM, Jacob Carlborg wrote:
> On 2016-01-07 21:18, ZombineDev wrote:
>
>> A) Local http server that you can start like so:
>> cd dmd
>> make serve-dmd-docs
>> browser 127.0.0.1:8080/dmd-internal-docs
>
> What would be the point of the web server? Talk about adding complexity and
> dependencies. It's enough to generate the HTML, CSS and JavaScript. Then just
> open the files in your browser. Not need to have a web server running.

In Windows anyway, merely typing:

   foo.html

at the command prompt brings up foo.html in the browser. This is very convenient.