Fix gtkD api display

Johnson Jones via Digitalmars-d-learn digitalmars-d-learn at puremagic.com
Fri Aug 4 14:53:14 PDT 2017


On Friday, 4 August 2017 at 13:59:11 UTC, Adam D. Ruppe wrote:
> On Friday, 4 August 2017 at 02:08:31 UTC, Johnson Jones wrote:
>> https://api.gtkd.org/gtkd/gtk/ApplicationWindow.html
>
> So I ran gtkd through my doc generator too
>
> http://dpldocs.info/experimental-docs/gtk.ApplicationWindow.ApplicationWindow.html
>
> and I didn't make a top-level package file either... but doing 
> that wouldn't be hard. However, I noticed it is basically the 
> same as the official C documents: 
> https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html so idk if it is worth spending a lot of time on it.

Looks nicer in some ways and in others I prefer the original.

I particularly like the members list. The use of the different 
font sizes, colors, and boxes/lines help contrast elements well.

When I click on gtk on the link you gave it gives basically an 
empty page(a single module). If I click on ApplicationWindow it 
takes me to a page that lists all the members on the left, which 
is nice. Probably minor bugs or issues.

e.g.,

http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html


Does not list any members to the left.

The left list should be an independent panel. When one scrolls 
down to view a long page one doesn't want to have to scroll all 
the way back up to view the members list again. It results in a 
slower process. Seems that is how many of the D docs are but it's 
wrong/unnecessary as it slows searching down. e.g., the original 
gtkD docs have a scrollable panel like I'm talking about, but 
they just list one module at a time, which makes it difficult:

https://api.gtkd.org/gtkd/gtk/AboutDialog.html

and

https://developer.gnome.org/gtk3/stable/GtkApplicationWindow.html

has no side panel.

So, with a little tightening up, I'd definitely prefer your docs 
over the other two versions. (It's always good to have multiple 
versions though)

I think any type of documentation should aim at two goals: As 
much information as possible and to quickly access any point in 
that information from any other point with information points 
that are closer being more quickly accessed(A metric). The way 
the info is organized is, of course, going then to be dependent 
on the above.

Since many programs spend a significant portion of their life 
searching through docs online, I think it's important to optimize 
that routine. Would be nice if programmers learned to optimize 
not only programs but the art of programming itself... we'd all 
get much more done. After all, many of the same principles apply. 
But things are way better than they used to be, so that's a good 
sign ;)

I'm not sure what Geralds docs look like but it might solve many 
of the problems already and you don't have to waste your time if 
you don't want to. OTH, since you are using an automated utility, 
it might be worth while to optimize it a little more since it 
will effect everything it's used on(although, I don't know how 
time consuming it would be to rerun it on all the docs you've 
generated... hopefully you've automated that too ;).


Thanks.




More information about the Digitalmars-d-learn mailing list