Fix gtkD api display

Johnson Jones via Digitalmars-d-learn digitalmars-d-learn at puremagic.com
Fri Aug 4 17:57:27 PDT 2017


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.


More information about the Digitalmars-d-learn mailing list