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.

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.

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.

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?

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

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

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

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.

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.

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