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.
