www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - dpldocs: xlinking and Documented destructors and postblits

reply Adam D. Ruppe <destructionator gmail.com> writes:
I stumbled across std.typecons.Unique in my doc website today and 
realized there was a postblit in the source, but I didn't display 
the documentation comment.

Aghast at my awful bug, I immediately set out to fix it. Behold:

http://dpldocs.info/experimental-docs/std.typecons.RefCounted.html#destructor

Now, mind you, dpldocs remains buggy in a few places. I'm not 
happy with how I display the `alias this` for example... but I am 
kinda proud that I *do* actually display it. Similarly, the link 
in the destructor goes sort of to the right place, but not quite 
- it leaves you two clicks short. I'll fix that. But on the other 
hand, click through to many of the other things, like the enum 
values referenced in the introduction. My generator brings you 
right to the enum page, highlighting the specific value!

Similarly, I now display destructors, postblits, alias this, and 
disabled default constructors, whether they have ddoc or not. And 
if they do, I display it. The user needs to know about those 
things, otherwise the code is a mysterious black box!

Contrast to the official docs:

http://dlang.org/library-prerelease/std/typecons/ref_counted.html

I'm actually a bit surprised that the documentation comments 
written in that source have NEVER BEFORE been displayed online! 
Someone took the effort to write those docs, but the generators 
all discarded them.

Y'all maintaining ddoc and ddox should file bugs ;) At the very 
least, you should display everything that has explicit ddoc 
comments attached!

Or better yet, surrender to me! D is gaining features that ddoc 
doesn't even know how to handle.... but I do...
Feb 28 2017
next sibling parent reply lobo <swamp.lobo gmail.com> writes:
On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:

 I stumbled across std.typecons.Unique in my doc website today 
 and realized there was a postblit in the source, but I didn't 
 display the documentation comment.

 [...]


Is it possible to use your tool to generate the docs for my own 
code?

Thanks,
lobo
Feb 28 2017
next sibling parent rikki cattermole <rikki cattermole.co.nz> writes:
On 01/03/2017 7:19 PM, lobo wrote:

 On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:

 I stumbled across std.typecons.Unique in my doc website today and
 realized there was a postblit in the source, but I didn't display the
 documentation comment.

 [...]


 Is it possible to use your tool to generate the docs for my own code?

 Thanks,
 lobo


Link[0].

[0] https://github.com/adamdruppe/adrdox
Feb 28 2017
prev sibling next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 1 March 2017 at 06:19:30 UTC, lobo wrote:

 Is it possible to use your tool to generate the docs for my own 
 code?


Yes, but I don't actually support it yet (you can grab the code 
from the link rikki gave but you're on your own).

I work on this in between the other million things I have to do, 
so we are probably still a bit away from this, but once I'm happy 
with the feature set, I'll call it "beta" in the header and start 
supporting it for other people, through a download of the 
generator or probably an upload to my site of a zip of your 
project.

My ideal end goal is to have a combined search too btw, so you 
can find docs for anything from the dpldocs.info homepage.
Mar 01 2017
prev sibling parent lobo <swamp.lobo gmail.com> writes:
On Wednesday, 1 March 2017 at 06:19:30 UTC, lobo wrote:

 On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:

 I stumbled across std.typecons.Unique in my doc website today 
 and realized there was a postblit in the source, but I didn't 
 display the documentation comment.

 [...]


 Is it possible to use your tool to generate the docs for my own 
 code?

 Thanks,
 lobo


Thanks, I'll give it a try.

lobo
Mar 01 2017
prev sibling next sibling parent reply "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 03/01/2017 12:18 AM, Adam D. Ruppe wrote:

 Or better yet, surrender to me! D is gaining features that ddoc doesn't
 even know how to handle.... but I do...


http://www.youtube.com/watch?v=lBEn3a4TIUw&t=0m11s

But seriously though, nice job!
Feb 28 2017
parent "Nick Sabalausky (Abscissa)" <SeeWebsiteToContactMe semitwist.com> writes:
On 03/01/2017 01:56 AM, Nick Sabalausky (Abscissa) wrote:

 On 03/01/2017 12:18 AM, Adam D. Ruppe wrote:

 Or better yet, surrender to me! D is gaining features that ddoc doesn't
 even know how to handle.... but I do...


 http://www.youtube.com/watch?v=lBEn3a4TIUw&t=0m11s

 But seriously though, nice job!


(There needs to be a language based entirely on Youtube links. Take 
that, Darmok and Jalad at Tanagra!)
Feb 28 2017
prev sibling next sibling parent Sebastiaan Koppe <mail skoppe.eu> writes:
On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:

 Contrast to the official docs:

 http://dlang.org/library-prerelease/std/typecons/ref_counted.html


my 2 cents:

The officials docs has too much grey and the information is not 
where you expect it to be. Yours is way more readable to me.
Feb 28 2017
prev sibling next sibling parent reply bachmeier <no spam.net> writes:
On Wednesday, 1 March 2017 at 05:18:59 UTC, Adam D. Ruppe wrote:

 Or better yet, surrender to me! D is gaining features that ddoc 
 doesn't even know how to handle.... but I do...


If by "surrender", you mean adopt your system for the official 
documentation, well I sure hope not. That's a fast way to kill 
progress on anything related to this language.
Mar 01 2017
parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 1 March 2017 at 12:05:33 UTC, bachmeier wrote:

 If by "surrender", you mean adopt your system for the official 
 documentation, well I sure hope not. That's a fast way to kill 
 progress on anything related to this language.


Yeah, I'd prolly have to continue working on it myself but they 
could fork off a stable version to use on the website.

Regardless though, I'd also be happy if the competitive pressure 
leads to improvements on the main site (while I continue to be 
streets ahead on my own site).
Mar 01 2017
parent reply Seb <seb wilzba.ch> writes:
On Wednesday, 1 March 2017 at 20:10:35 UTC, Adam D. Ruppe wrote:

 On Wednesday, 1 March 2017 at 12:05:33 UTC, bachmeier wrote:

 If by "surrender", you mean adopt your system for the official 
 documentation, well I sure hope not. That's a fast way to kill 
 progress on anything related to this language.


 Yeah, I'd prolly have to continue working on it myself but they 
 could fork off a stable version to use on the website.

 Regardless though, I'd also be happy if the competitive 
 pressure leads to improvements on the main site (while I 
 continue to be streets ahead on my own site).


Hehe, well for those who haven't been following closely. Jack and 
I are putting some effort into improving the "official" 
documentation:

https://github.com/dlang/phobos/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Adocumentation%20

Most of these changes are independent from Ddoc/Ddox/Adrdox/..., 
so everyone should be able to enjoy cleaner documentation soon.

 Adam: I like your docs as well!
Have you ever considered adding vibe.d to them?
Mar 01 2017
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 1 March 2017 at 23:21:14 UTC, Seb wrote:

 https://github.com/dlang/phobos/pulls?utf8=%E2%9C%93&q=is%3Apr%20label%3Adocumentation%20

 Most of these changes are independent from 
 Ddoc/Ddox/Adrdox/..., so everyone should be able to enjoy 
 cleaner documentation soon.


Actually, almost none of that affects me! (Except perhaps causing 
more merge conflicts for me when I pull, alas, but that's the 
downside of doing a fork. I already killed most the LUCKY links, 
for example, and the booktables are redundant (though basically 
harmless) with my automatically generated listings.

My diff from upstream is now over 5300 lines long, including a 
mix of formatting, syntax, linking, and some content changes...


  Adam: I like your docs as well!
 Have you ever considered adding vibe.d to them?


Once I'm happy with it, I might scrape code.dlang.org and pull it.

Though it is important to note that adrdox does NOT support 
user-defined ddoc macros, so not everything with ddoc will just 
work. I hardcoded a bunch of the common Phobos ones, but my goal 
ideally is to eliminate most macros in favor of things taking 
care of themselves with lightweight syntax (which ironically, was 
part of ddoc's original charter!)
Mar 01 2017
parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 2 March 2017 at 00:06:17 UTC, Adam D. Ruppe wrote:

 Though it is important to note that adrdox does NOT support 
 user-defined ddoc macros


But, it DOES now support a footnote kind of thing. Behold:

http://dpldocs.info/experimental-docs/test.html#footnotes

In ddoc, I was tempted to define a $(RANGE_CONCEPT Input) macro 
or something like that, which would expand do $(REF 
std,range,primitives,is$1Range, $1 range) or something along 
those lines (of course, ddoc is so underpowered that wouldn't 
even be that good..) because right now we repeat those references 
a LOT.

(Actually, I don't love linking to isInputRange's function 
definition. I'd prefer a higher-level overview of ranges when we 
link it, but isInputRange is the best we have written right now 
outside our various books.)

adrdox makes it a bit nicer, `[isInputRange|input range]` will do 
what's needed, as long as `std.range.primitives` is imported in 
scope (which it typically is for the constraint anyway), but what 
if we write a new conceptual article and want to change the links?

That's what led me to the Link_References idea. By defining:

concept_input_range = [isInputRange|input range]

we can just reference text like `It must be an 
[concept_input_range]` and be a bit more DRY (and btw 
concept_input_range is easier on my autocomplete algorithms than 
isInputRange|input range... and infinitely better than the ddoc 
macro mess.)

So, I went ahead and implemented that today. And footnotes, 
images, and popup text is easy to do in the same framework and 
sometimes useful too, so I just did it all together.


My generator isn't just about reading more semantics out of D, it 
is also about making something easier to use than ddoc.
Mar 01 2017
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Wednesday, 1 March 2017 at 23:21:14 UTC, Seb wrote:

  Adam: I like your docs as well!
 Have you ever considered adding vibe.d to them?


I just ran the generator over them now (though I did NOT add them 
to the search index or the source listing so you can't search or 
view source, but you can navigate):

http://dpldocs.info/experimental-docs/vibe.html

The generator did a decent job handling it, though some 
interlinking came out wonky, I'll have to look into that... but 
still, take a look.

As you might expect, I like mine better than the official site, 
even with my minor bugs. Take a look at this, for example:

http://vibed.org/api/vibe.http.server/HTTPServerOption

vs

http://dpldocs.info/experimental-docs/vibe.http.server.HTTPServerOption.html

I just find mine so much easier on the eyes. My nav is also far 
easier than the ddox one IMO. My sidebar only shows siblings and 
parents of the current decl, keeping it a flat list. It is less 
stuff instantly there, but it is so easy to click the parent that 
I don't get lost on mine and often do in the JS collapsible tree.
Mar 04 2017
prev sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
Seeing ddmd coming to dlang.org 
<https://dlang.org/phobos-prerelease/ddmd_access.html>, just for 
fun I ran my doc generator over the dmd source code too: 
http://dpldocs.info/experimental-docs/ddmd.html I didn't enable 
search over it but you can browse to the extent that there are 
ddoc comments in there.

This is an interesting case to look at because dmd is pretty 
class-heavy... and my class handling is OK, but not great.

Like here, it shows inherited members from Declaration, but not 
from Dsymbol.

http://dpldocs.info/experimental-docs/ddmd.declaration.AliasDeclaration.html

but hey at least you can navigate up the tree with just a few 
clicks anyway.
Mar 01 2017