https://api.gtkd.org

It is difficult to navigate.

1. clicking the documentation on the main site takes it to the gtk.AboutDialog api. That is all it shows, I was confused at first, as I'm sure most people would be.

2. The packages list lists all the packages, but all the sub elements are expanded, making it time consuming to hunt down anything specific. Initially collapsing them and adding a search box would be nice.

3. When clicking on any packages it reloads the page and shows only the package in the first tab. This requires one to then go back to packages and hunt for something else again. Because the position of the scroll is not saved, one has to scroll down through the entire list.

It would be better, I think, if it was one single tab all in a single hierarchy that never reloaded the page so that it is easier to navigate quickly.

e.g.,

instead of

Package
atk
  atk.ActionIF
  atk.Action
  ...

we have

atk
  atk.ActionIF
     GetActionStruct
     GetStruct
     ...
  atk.Action
     ...
...


and so effectually combining both tabs. It should solve the issues that the current way has without really causing any problems. Everything should be collapsed by default and since no reloading of the page should occur(which might require having the api descriptions in a separate frame that is loaded separately on package changes to avoid reloading the tree view which will recollapse everything).

It will make navigating the gtkD api much more fun ;)

Also, interfaces are not linkable.

e.g., for gtk.ApplicationWindow, it inherits from gtk.Window but I have to go back to the packages and scroll down to find gtk.Window to see it's properties and methods. Would be nice if I could just click on the gtk.Window and it jump me to it.

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

class ApplicationWindow : gtk.Window.Window, gio.ActionGroupIF.ActionGroupIF, gio.ActionMapIF.ActionMapIF;

since the hierarchy is gtk/Window/Window, click on gtk should take one to the gtk package, the first Window should take one to gtk.Window and the second should take one to gtk.Window.Window

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.

On 04-08-17 03:51, Johnson Jones wrote:
> https://api.gtkd.org
> 
> It is difficult to navigate.
> 
> 1. clicking the documentation on the main site takes it to the gtk.AboutDialog api. That is all it shows, I was confused at first, as I'm sure most people would be.
> 
> 2. The packages list lists all the packages, but all the sub elements are expanded, making it time consuming to hunt down anything specific. Initially collapsing them and adding a search box would be nice.
> 
> 3. When clicking on any packages it reloads the page and shows only the package in the first tab. This requires one to then go back to packages and hunt for something else again. Because the position of the scroll is not saved, one has to scroll down through the entire list.
> 
> It would be better, I think, if it was one single tab all in a single hierarchy that never reloaded the page so that it is easier to navigate quickly.
> 
> e.g.,
> 
> instead of
> 
> Package
> atk
>    atk.ActionIF
>    atk.Action
>    ...
> 
> we have
> 
> atk
>    atk.ActionIF
>       GetActionStruct
>       GetStruct
>       ...
>    atk.Action
>       ...
> ...
> 
> 
> and so effectually combining both tabs. It should solve the issues that the current way has without really causing any problems. Everything should be collapsed by default and since no reloading of the page should occur(which might require having the api descriptions in a separate frame that is loaded separately on package changes to avoid reloading the tree view which will recollapse everything).
> 
> It will make navigating the gtkD api much more fun ;)

Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier.

So unless somebody volunteers it won't happen anytime soon.

-- 
Mike Wey

On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:
> Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier.
>
> So unless somebody volunteers it won't happen anytime soon.

Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work.

The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.

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.

On Friday, 4 August 2017 at 15:24:51 UTC, Gerald wrote:
> On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:
>> Improving the documentation is something i want to do but there are always some more important things to do. Like the Questions/Issues you posted earlier.
>>
>> So unless somebody volunteers it won't happen anytime soon.
>
> Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work.
>
> The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.

Is there any online demo of it working?

Thanks.

On Friday, 4 August 2017 at 21:53:14 UTC, Johnson Jones wrote:
> When I click on gtk on the link you gave it gives basically an empty page(a single module).

Yeah, there is no overview page in the source code... but I can make it create one automatically.


> http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html
>
> Does not list any members to the left.

That's intentional, actually. For the left nav, I show parents and siblings, not children (that's in the main content on the right). I sometimes miss children there too, but siblings are actually usually more useful to me.

Easier to see the value in Phobos since it is flatter:
http://dpldocs.info/experimental-docs/std.algorithm.sorting.isSorted.html

you can see the bolded isSorted showing where you are now, and then its other siblings to navigate the module over there.


gtkd has really shallow modules with just one class per module, so this appears less useful... but in general I find it really easily to navigate. Maybe I could detect the one class per module pattern and collapse it though.

> 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.

See, this is why I DON'T use a tree over there. There's just way too much scrolling in a tree, both vertical and horizontal. By just showing parents and siblings, it presents the most useful info without needing scrolling... it just doesn't work well for one class per module.


> Since many programs spend a significant portion of their life searching through docs online, I think it's important to optimize that routine.

That's why I forked the docs... everyone else was just doing the same boring crap so I went something fairly different.

> 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.

It sounds like ddox which is one option I evaluated and rejected when I did my fork... so it might be ok but I doubt it is better.

The official gtk docs are the competition and I don't actually like them either...

> 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 ;).

Simple case of running ./doc /path/to/gtk and waiting like 5 mins for it. So it is slow but automatic so I can just do it in the background.

I just hate running big disk operations on my computer... so I need to optimize this since I run so many docs now.

On Friday, 4 August 2017 at 21:54:26 UTC, Johnson Jones wrote:
> On Friday, 4 August 2017 at 15:24:51 UTC, Gerald wrote:
>> On Friday, 4 August 2017 at 15:08:27 UTC, Mike Wey wrote:
>>> [...]
>>
>> Mike I had contributed the makeddox.sh script awhile ago, it generates much nicer documentation then candydocs in my IHMO and includes a nice search box. If there is something lacking in it that needs to be improved before it can be used let me know and I'll do the work.
>>
>> The only issue with it that I am aware of is you need to manually copy the public ddox css into the generated folder. I didn't see an easy way to determine it's location automatically.
>
> Is there any online demo of it working?

Unfortunately there is not, I just run it locally on my laptop.

On Friday, 4 August 2017 at 23:14:38 UTC, Adam D. Ruppe wrote:
> On Friday, 4 August 2017 at 21:53:14 UTC, Johnson Jones wrote:
>> When I click on gtk on the link you gave it gives basically an empty page(a single module).
>
> Yeah, there is no overview page in the source code... but I can make it create one automatically.
>
>
>> http://dpldocs.info/experimental-docs/gtk.HButtonBox.HButtonBox.html
>>
>> Does not list any members to the left.
>
> That's intentional, actually. For the left nav, I show parents and siblings, not children (that's in the main content on the right). I sometimes miss children there too, but siblings are actually usually more useful to me.
>
> Easier to see the value in Phobos since it is flatter:
> http://dpldocs.info/experimental-docs/std.algorithm.sorting.isSorted.html
>
> you can see the bolded isSorted showing where you are now, and then its other siblings to navigate the module over there.
>

Yeah, that is a nice feature. But I do not think we are talking about the same thing.

While having the siblings only is also nice and desirable to reduce clutter, one needs to quickly see all methods in a module rather than having to hunt and peck.

This is actually done in the phobos link you gave and is what am I talking about. The problem then is that we do not see the hierarchy of all the modules and how they relate without having to click clinks.

e.g.,

http://dpldocs.info/experimental-docs/std.algorithm.sorting.nextPermutation.html

but

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

shows all the modules in the main view which is very long and takes time to scroll. It would be nice if those were shown in the left pane rather than nothing.

This way, instead of having to scroll down the long list to find a module one can see it usually instantaneously to the left. Basically the same as the functions that are listed in the first link.

The way I would do it, probably, is to have a complete hierarchy tree.

std
   ...
   experimental
      ...
      allocator
         ...
         building_blocks
            ...
            region
               ...
               InSituRegion


Now, obviously this is a very big list. (For speed, probably ajax would be used to load only the most relevant)

Also, everything cannot be expanded at the start. Only the most current position is expanded + any siblings.

So, it is sorta like what you have but offers a way to see the entire library and navigate it relatively quickly but without having to leave that panel to find something. It's all their, just not the descriptions, etc.(although mouse over could provide some basic description when required)

Because humans are amazing and have figured out vast ways to do things, I'd probably have a small toolbar at the top that lets one go between different views. If you want a flat list you click the flat button. If you want a full hierarchy you can click a button for that. If you want a reduced hierarchy(immediate module only, still in tree form but all the other branches off the root are not shown) you could get that. Siblings only would have a button.

Since all these are basically just different "views" of the same data, they all have their pros and cons and some are more useful than others at different times. The more ways one can view data the more ways one can understand the data.



>
> gtkd has really shallow modules with just one class per module, so this appears less useful... but in general I find it really easily to navigate. Maybe I could detect the one class per module pattern and collapse it though.

My problem with gtkD's docs is that one cannot quickly(within a click) go from one module to another.

One must select the packages tab then find the module and click on it. Do whatever, then when one wants to go to another module, repeat the process. It's not slow in an absolute sense(whatever that means) but it takes a few seconds when it can be done < 1s.

Since the packages and module are tabbed, one can't have them both open. If they were side by side, it would probably work fine... not much different than a tree view.

Also, the package tree is not collapsed by default. This means more scrolling. Scrolling is a slow process. It may seems fast but it's just a waste of time ultimately because we cannot do anything while we are doing it... and all those little scrolls add up to significant time loss. It's similar to how banks try to get a few extra cents per customer because it's billions at the end of the day... or how manufactures try to cut costs on a product that are a few cents work per product but add up to billions.  Similar for programmers. Imagine if we could instantly find the help we wanted how much more time we would have over our lives. E.g., some type of brain interface device that we could transmit our thoughts in to and it would do a search for the data and present the results. That is effectively what we have with google or whatever computer searching tools.. but it far slower than a direct connection.



>> 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.
>
> See, this is why I DON'T use a tree over there. There's just way too much scrolling in a tree, both vertical and horizontal. By just showing parents and siblings, it presents the most useful info without needing scrolling... it just doesn't work well for one class per module.

I agree, in most cases for programming docs(or file systems, say) this is true. But most of the time the tree should be completely collapsed at all levels so within O(log2(depth)) clicks we can find what we want. Usually the depth is not more than 10 so it takes just a few clicks to find(usually about 3 to 4). These clicks are better than scrolling because to scroll we have to move the cursor to the scroller and then back and click. When we click generally it is a smaller distance to move because the information is localized on the screen(e.g., we click on the parent then on a child which is somewhere below the parent, but usually not too far off).

If humans organized things better we wouldn't have such problems. Hierarchies that are effectively a flat list(e.g., a folder with 1M sub-folders in it) is not designed properly for optimal searching and effectively is not a hierarchy. (We end up with O(n) searching rather than O(log(n))).



>
>> Since many programs spend a significant portion of their life searching through docs online, I think it's important to optimize that routine.
>
> That's why I forked the docs... everyone else was just doing the same boring crap so I went something fairly different.

That's good, that's what it takes for progress. Most people are lemmings and don't have any imagination and can't or won't think outside the box. Why humans have progressed to where they are is someone being tired of the same old boring and broke shit and decided to find a better way.


>> 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.
>
> It sounds like ddox which is one option I evaluated and rejected when I did my fork... so it might be ok but I doubt it is better.
>
> The official gtk docs are the competition and I don't actually like them either...
>
>> 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 ;).
>
> Simple case of running ./doc /path/to/gtk and waiting like 5 mins for it. So it is slow but automatic so I can just do it in the background.
>
> I just hate running big disk operations on my computer... so I need to optimize this since I run so many docs now.

Could you automate this better using a "cloud" based strategy? Something like github or a remote server where you have all the docs uploaded to and can trigger an update which causes it to update the documentation and then a rebuild which builds the docs? This way it should only take a few seconds to start the process and everything will be done remotely not effecting your own time much(of course the design/setup time might be costly but probably not too bad).


IMO, the modern documentation sucks. I remember doing win32 stuff back in the day of win95/98 and microsoft had all the docs with visual studio 2005. The documentation was extremely informative rather than just a list of functions and parameter descriptions. They'd give you the theory, the relationships between everything, etc. It wasn't that easy to navigate but it wasn't a big deal because most of the time was spent reading and clicking links. Now, since the actual information is so frugal, one spends more time searching for stuff and therefor the searching time is more of an issue.


For example:


----
InSituRegion
struct InSituRegion(size_t size, size_t minAlign = platformAlignment)

    InSituRegion is a convenient region that carries its storage within itself (in the form of a statically-sized array).
Region
struct Region(ParentAllocator = NullAllocator, uint minAlign = platformAlignment, Flag!"growDownwards" growDownwards = No.growDownwards)

    A Region allocator allocates memory straight from one contiguous chunk. There is no deallocation, and once the region is full, allocation requests return null. Therefore, Regions are often used (a) in conjunction with more sophisticated allocators; or (b) for batch-style very fast allocations that deallocate everything at once.
SbrkRegion
struct SbrkRegion(uint minAlign = platformAlignment)

    Allocator backed by $(LINK2 https://en.wikipedia.org/wiki/Sbrk, sbrk) for Posix systems. Due to the fact that sbrk is not thread-safe by design, SbrkRegion uses a mutex internally. This implies that uncontrolled calls to brk and sbrk may affect the workings of SbrkRegion adversely.
----

Basically tells me nothing about how to use these things nor how they work with the whole design of allocator. It may be somewhat straight forward in some cases but in others it's helpful to know theory. To get that, I have to track down where the information is, if it exists. It is backwards than what it used to be which was a top down approach(a hierarchy starting with the root).

e.g., You might start with a section on memory management that describes how it works and all that and it would then break off in to the more detailed aspects and those then would break off. As you learn about them you start with the most general understanding and learn the specifics... which is how the human brain learns. Now we seem to just deal with specifies. Generalities must be learned from other sources and one must try and piece everything together. Of course, this is probably due to isolated individuals writing the docs rather than a team that actually plans out everything...

The D docs sorta try to do the top down approach so there is info there but I don't get the same feeling I get from the win32 docs(which, some time later MS$ changed the help system and everything started going down hill). I think it's because the win32 help design was just very well put together. It didn't feel like a cobbling of different statements but a very well thought out explanation of the entire system.

In any case, thanks for working on this stuff! It benefits a lot of people.