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
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
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
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
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
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
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
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
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
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
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
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
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
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
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