View mode: basic / threaded / horizontal-split · Log in · Help
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 10:08:17 UTC, Dmitry Olshansky 
wrote:
> I'll give it a whirl.

cool. BTW search the code for the word "HACK". There's one that 
rewrites css links to be absolute and one that adds some inline 
style.

Those are there so I can test it from a different domain that 
doesn't have the whole website available. Probably safe to leave 
them there, but surely cleaner to comment that out before 
committing to the real thing.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 11:01:50 UTC, Jacob Carlborg 
wrote:
> Is it just me that thinks that having a tool that fixes the 
> generated documentation is ridiculous. The compiler should be 
> modified to generate the documentation we want to have.

Eh, maybe. I just find doing fancier things inside the compiler 
to be a pain in the butt. Basically D > C++. And it is harder to 
get code into dmd than it is to just do your own thing.

But really what matters is that we get something that doesn't 
suck results wise. We could always change the ddoc implementation 
later.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 11:35:48 UTC, JN wrote:
> TickDuration should be a clickable link leading to 
> core.time.TickDuration class docs.

Yeah, I looked for that once before too, but the current 
implementation makes that difficult. IIRC the compiler has 
already stringified that data by the time it gets to the 
documentation generation code, so the details aren't really 
available.

I do vaguely recall seeing someone post a proper solution to 
github or bugzilla once though.

Another possibility is to connect it through to a search engine. 
My (currently low quality) dpldocs.info does an ok job:

http://dpldocs.info/TickDuration


So we could just wire all clicks to go through that. Somehow. But 
I think that's still suck hard because it couldn't tell what 
words to allow to be clickable and would have pointless ambiguity 
compared to the compiler just showing the right data.


idk, I just kinda hate doing C++ too. D has spoiled me.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 13:48:41 UTC, Adam D. Ruppe wrote:
> On Sunday, 30 September 2012 at 11:01:50 UTC, Jacob Carlborg 
> wrote:
>> Is it just me that thinks that having a tool that fixes the 
>> generated documentation is ridiculous. The compiler should be 
>> modified to generate the documentation we want to have.
>
> Eh, maybe. I just find doing fancier things inside the compiler 
> to be a pain in the butt. Basically D > C++. And it is harder 
> to get code into dmd than it is to just do your own thing.
>
> But really what matters is that we get something that doesn't 
> suck results wise. We could always change the ddoc 
> implementation later.

Which is why the doc generation utility should be a separate tool 
and not built directly into the compiler. I understand Walter's 
desire to have batteries included with D (doc generation, 
unit-testing, profiling, ...) but that does not mean they should 
be welded in. The DMD distribution could just as well provide a 
set of auxiliary _standalone_ utilities for that.

DMD already has JSON output. Can't that be standardized and used 
with a separate ddoc utility written in D?
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On 2012-09-30 17:00, foobar wrote:

> Which is why the doc generation utility should be a separate tool and
> not built directly into the compiler. I understand Walter's desire to
> have batteries included with D (doc generation, unit-testing, profiling,
> ...) but that does not mean they should be welded in. The DMD
> distribution could just as well provide a set of auxiliary _standalone_
> utilities for that.

And we're back at the fact that we need a compiler library.

-- 
/Jacob Carlborg
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On 2012-09-30 15:49, Adam D. Ruppe wrote:

> Eh, maybe. I just find doing fancier things inside the compiler to be a
> pain in the butt. Basically D > C++. And it is harder to get code into
> dmd than it is to just do your own thing.
>
> But really what matters is that we get something that doesn't suck
> results wise. We could always change the ddoc implementation later.

That might be true but it's this kind of attitude that makes the source 
code a big mess and software suck. It's always "we fix this later", well 
"later" is never going to happen. It's always patch on workaround on fix 
on patch, and so on. What's wrong with "hey, lets fix this the right way 
for a change".

-- 
/Jacob Carlborg
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 15:31:30 UTC, Jacob Carlborg 
wrote:
> And we're back at the fact that we need a compiler library.

Not necessarily... the ddoc comments are available in the 
compiler's json output (use -X and -D together in dmd). It 
doesn't do syntax highlighting and could offer a lot more info 
than it does now... but it does give enough to approximate your 
own ddoc.

I'm using the json output for dpldocs.info version two:
http://dpldocs.info/search/search?searchTerm=std.regex
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 15:36:50 UTC, Jacob Carlborg 
wrote:
> What's wrong with "hey, lets fix this the right way for a 
> change".

If you want to write the code, feel free.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On Sunday, 30 September 2012 at 15:41:46 UTC, Adam D. Ruppe wrote:
> If you want to write the code, feel free.

I'm sorry, this probably came across as rude, but the answer for 
why not do it the right way is simply that the right way takes 
time and I don't feel like putting it in. Apparently not very 
many other people do either, since we've had the status quo for a 
long time now.

A quick helper app can be slapped together in a fraction of the 
time of a more proper fix.
September 30, 2012
Re: Getting started with D - Phobos documentation sucks
On 2012-09-30 17:37, Adam D. Ruppe wrote:
> On Sunday, 30 September 2012 at 15:31:30 UTC, Jacob Carlborg wrote:
>> And we're back at the fact that we need a compiler library.
>
> Not necessarily... the ddoc comments are available in the compiler's
> json output (use -X and -D together in dmd). It doesn't do syntax
> highlighting and could offer a lot more info than it does now... but it
> does give enough to approximate your own ddoc.
>
> I'm using the json output for dpldocs.info version two:
> http://dpldocs.info/search/search?searchTerm=std.regex

If think the whole idea of the JSON output is a workaround for not 
having the compiler available as a library.

-- 
/Jacob Carlborg
1 2 3 4 5
Top | Discussion index | About this forum | D home