www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Browsing D compiler source code

reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Jan 07 2016
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jan 07 2016
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Jan 07 2016
parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Jan 07 2016
prev sibling next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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.
Jan 07 2016
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Jan 07 2016
parent reply ZombineDev <valid_email he.re> writes:
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?
Jan 07 2016
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jan 07 2016
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Jan 07 2016
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Jan 08 2016
parent Jacob Carlborg <doob me.com> writes:
On 2016-01-08 15:25, Walter Bright wrote:


 In Windows anyway, merely typing:

     foo.html

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


Exactly. On OS X, prepend with "open".

-- 
/Jacob Carlborg
Jan 08 2016
prev sibling parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 08.01.2016 um 08:54 schrieb Jacob Carlborg:

 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.


The main advantage is that generating (all) the files can be quite slow 
and when you want get quick previews of the documentation you're working 
on, generating them on the fly is much quicker.

BTW, in the dlang.org repository you can do "make -f xxx.mak 
apidocs-serve" to get that (of course only for Druntime and Phobos).
Jan 09 2016
prev sibling parent reply Bubbasaur <bubba gmail.com> writes:
On Thursday, 7 January 2016 at 14:32:32 UTC, Walter Bright wrote:

 ...the D compiler source should be, too...


Someone could explain what's the difference between having a 
source code browsable here vs github?

Bubba.
Jan 08 2016
parent reply Jacob Carlborg <doob me.com> writes:
On 2016-01-08 20:49, Bubbasaur wrote:


 Someone could explain what's the difference between having a source code
 browsable here vs github?


If you read the whole post you can see that it's about generating 
documentation from the DMD source code.

-- 
/Jacob Carlborg
Jan 09 2016
parent Bubbasaur <bubba gmail.com> writes:
On Saturday, 9 January 2016 at 10:23:02 UTC, Jacob Carlborg wrote:

 On 2016-01-08 20:49, Bubbasaur wrote:


 Someone could explain what's the difference between having a 
 source code
 browsable here vs github?


 If you read the whole post you can see that it's about 
 generating documentation from the DMD source code.


In fact I read, but I had misunderstood:

"Like the Phobos Ddoc output is browsable on dlang.org, the D 
compiler source should be, too."

I thought he was just using the Phobos Ddoc as example, and 
wanting to do the same with the D Compiler.

Bubba.
Jan 09 2016