Documentation URLs and quick access

documentation

#1

Hi,

I just noticed that the API documentation urls have changed. I used to have a shortcut in my browser that redirected me to

https://www.juce.com/doc/classComponent

when I typed ‘j Component’ in the address bar. That was very convenient for quick access to the juce documentation of a given class. However the component doc is now at:

https://www.juce.com/doc/group__juce__gui__basics-components#classComponent

So I can’t use that shortcut trick anymore since the url now contains module name.

How to people handle the juce documentation, are there other tricks for quick access to the doc of a juce class ? searching in the class index at https://www.juce.com/doc/classes is really not convenient.


#2

I use my IDE almost exclusively - all of the good ones have a “jump to definition” or similar where you can see and search the class documentation. Xcode can even display the docs of a method inline.


#3

I think this (unintended?) change is a disaster. Every single google search result that previously pointed to a solution or at least the correct documentation, is now broken.

Even typing something simple like “juce string” now points to the wrong URL.

All forum posts that point to solutions or specifics are broken.

This creates yet another barrier for JUCE newbies. The documention needs improvement, not further barriers. It’s dark purple on black with a thin font, for Christs sake. We dont need to make it worse by hiding it completely and marking it even harder to find.

Please reverse this ASAP and let someone else pick the colours, fonts etc.


#4

objection your honour.

I like the improvement, that the modules are displayed now. Finally I can see what is included in a specific module.

Give google a week, and things sort out themselves. Maybe someone nudges google with the admin tools…


#5

Sorry, don’t want to offend, but you’re being very selfish here. Every single link that people posted by hand, is now broken. The added information is NOT worth that. Give google a week? Google updates its results depending on the traffic. I don’t think it will take only a week. Some of these will take several months. Some will probably never update.

Again: it was hard enough as it was. The documentation was always lacking, always hard to find and hard to read. Adding another barrier because you prefer to have some extra bit of unnecessary information is not worth the price.

It would be nice to hear the official word. Was it intentionall? Will it be fixed?


#6

I think it is a good thing to embrace it, when the juce team tries to improve things. The documentation and the search capabilities have some room for improvement, so I’d rather not slam them for their effort.

This is a very subjective and a bit offensive statement.

I agree, that there has to be a mapping installed to keep the links in the forum working. Some URL-rewrite probably…

I don’t think it is helpful or makes the juce team working any harder by yelling around, how crappy they misbehaved… Keep it nice…

Anyway, I’m off this thread, I said all I had to say…


#7

Nobody is yelling or trying to make anyone’s job harder. We don’t even know if this was intentional or not.

Remember that these files are auto-generated. It might be a completely innocent mistake of some unintended configuration change or doxygen update.

Claiming it was an intended improvement and how my criticism is invalid, because we should encourage improvement in all it’s form, is gatekeeping at its best.

Apparently, as long as someone is trying hard enough, they are beyond criticism and should be left to continue to make mistakes. I wish people would do that with our work and our products.

I’m trying to be constructive here. I don’t criticize without solutions. Change the links back, or map them. Change the colours to have more contrast. Make the font bolder.

These are valid criticisms and stifling them in the name of “be nice” is counter productive.


#8

I don’t work for JUCE. Nor did I ask anybody to do it either way. What I do, is adding my view, that I liked the new structure. What you make of it is up to you.

I don’t want them to be changed back, because for me it is an improvement. We might just have different needs and workflows. But neither of us can make the others needs more or less valid. Things are just not always good or bad, sometimes there is more. We are a community and we have to live with each other.

Anyway, I am not deciding anything, so I leave it…


#9

I don’t understand you. I never claimed or implied your worked for ROLI/JUCE.

Nobody is claiming that adding information is a bad thing. It’s how it’s implemented that’s the problem.

Please be more constructive.


#10

This was an unintended change. As @daniel spotted we have grouped the classes by module (which is one of the more often requested features on here and the first step in a lot of documentation improvements we’ll be doing) which altered the underlying structure of the web pages.

I’ve added some 301 redirects for the old pages to the new pages and have gotten the web team to request a recrawl from Google. Eventually things will migrate to the new URLs and I could do something similar for all links posted on this forum too.


#11

Thanks, t0m.

Something that is not very convenient with the way the new doxygen doc is working, is that the webpage title is no more the name of the current displayed entry (String, Component, BusesLayout, etc) but the name of the module, for example the doc of

https://www.juce.com/doc/group__juce__audio__processors-format__types#classAudioUnitPluginFormat

just display ‘format_types’ in the browser tab.

So if you have many tabs opened on the juce documentation it is a bit confusing since they all have the same names.


#12

Thank you so much for fixing it.


#13

Sorry to open this again, but I think the new format is losing more than it gains. If you do a text-search on the documentation-pages now, you get TONS of results, but the vast majority are unrelated to the class/type you’re looking at.

Here’s an example: I was looking into the documentation of the ListBox class. Once the page came up, I searched for “header” on the page, because I vaguely remember that the ListBox class might be able to display a custom header. I got 187 results. The vast majority have nothing to do with the ListBox class, but rather with other functions/class/structs/types on that page.

Except the extra module information (which I understand is a good thing), why was everything merged into one page? It’s so extremely coarse and chaotic now.

Why can’t we have the old documentation, in the old format etc. just with the added information? Why does it have to be merged into one giant, slow to load, mega-page?


#14

+1 to this

The documentation is now borderline useless. It’s faster for me to go to the header files than browse the documentation online. It seems to me that this change is unfinished and should have been sandboxed before it was finished, because at the moment the documentation is extremely slow and impossible to search (another example, browse to any page and try and ctrl+F to find the setters/getters for a single class instead of all of them).

It seems to me you guys could have kept the old class pages and just added a “modules” page that lists the classes in a module, and links to redirect to the old documentation. Which is essentially what you have, except instead of the class documentation being a separate page, it’s all just plastered below the modules’ class listings.

I don’t think in the current state that the extra information is useful in the slightest, because you can’t exactly browse by module… the API page is still just a class listing, not a module listing. You have to know what you’re looking to for ahead of time.


#15

I think, most of the frustration is, that workarounds do no longer work. But this is pointing to the actual problem, that standard doxygen features are disabled (for layout reasons?)

Most important the API search field, that vanished over a year ago and never came back.
Also I am missing the various different indices, like Class hierarchy, Class members, Namespace etc.
At the moment the macros like JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR are not present at the documentation at all (If I am not blind).

I think, when this is fixed, people are way more forgiving with changes and (hopefully) improvements. But the basics need to be present.

I added these to the github issue, feel free everybody to add missing information there as well…

For the moment I can only recommend to install doxygen and create it yourself (run make in the doxygen folder).
Like some others, I create the docs for develop automatically and they are online on ffAudio/github, with search and menus.

Nevertheless, I appreciate that there is being worked on at all, that wasn’t the case for almost a year now. Please keep it going!

You can, it is present at the top of each page and it is a link that takes you to an overview of the module. On that page again, there is a link to the modules overview. Not great, but there is something…


#16

I’ve just ran the previous doxyfile on the documentation and it’s so much better than before, it’s not even funny anymore. The layout and colours alone are worth doing this, let alone getting a functional search. Heck, they even screwed up the inheritance diagrams. The default doxygen look isn’t pretty or modern, but it’s a whole lot better than anything ROLI ever came up with.

I’ll look into styling this next, and once I’m happy with it, I’ll take the new documentation public on my own server, for others to use.


#17

Please be patient while we reorganise the documentation. As I said previously, these changes are just the first steps towards some significant documentation improvements and we’ll be changing things regularly.

I can see that having multiple classes on one webpage makes it harder to parse and this is something we’ll remedy when we get to work on Monday morning.


#18

Somehow you managed to simultaneously (1) lose the search box (which should be generated by Doxygen anyway) (2) break Google search, and (3) break using the browser built-in search inside one class. Now, obviously, searching is a pretty important feature of documentation. I’ll be patient, but come on guys, this is quite messed up.

The solution is the same as one year ago. Install Doxygen and generate the documentation yourself.


#19

I know this thread is a bit volatile, but thank you for the prompt response and openness.


#20

As I’ve said, repeatedly now, we’re working on documentation improvements, so you will see changes as we try things out. There really is no need for such vitriol.

Google search was only broken for a couple of hours, a few days ago.

Having multiple classes on a single page was a side effect of grouping the classes by module, and, as of a few minutes ago, the old single-class-per-page format has been restored.

The Doxygen search box is now present at the top of each page.