Feedback on documentation needed! :)
-
I never use the docs site to look up things: It is just too clunky. So do whatever you want, as long as you do not mess up the pages in assistant. So please keep Qt Creator and assistant in mind when changing the stylesheets.
-
loladiro: Indeed, that is a very good suggestion. I also discovered a challenge - with the help of one of the other devnet users - that while hidden, it is impossible to find the text while doing a CTRL+F search.
The solution to the challenge would be to expand all the sections as you press CTRL+F. I will test this next week.Tobias: No worries - this version is for devnot only and is not part of the Qt library at all. However, I believer that the doc team would be happy to know about any suggestions on how to make the documentation better :)
-
Sounds good, keep us posted!
-
i would like the new design but if there is a collapse all / expand all button and a quick search in page.
-
the other visible advantage of this will be having the general class documentation directely at top of the page instead of having only a small part an a 'read more' link to see the rest....
-
I do think there are benefits, if the mentioned downsides can be fixed. One suggestion though, would be to remove the short explanation line. This line makes a quick visual scan more difficult. Instead, you could offer this information when hovering the item (make it expand a little at mouse over or as a tooltip-like popup), and of course show it when the item is expanded.
Also, I think the expand button should go in front of the item, not behind it. That is where expand buttons normally are (in tree-view like items and for code folding in Creator).
-
All: Thanks for the feedback! Many great suggestions. I believe that I can reach a solution that would make all(most) happy :)
-
I personally don't like the inline expansion. I often just scan the functions to check what exists. And if you open one, you have to close it again, otherwise there is too much between 2 functions from the list.
And think of people, checking 5 functions, with similar signatures or names, they open all 5 and then want to scan the list again, they would have to open all 5 (which are one under the other) and close all of them again. In the old docs, you jump to one with one click and have all 5 one under the other. And going back to the list is just one click then. -
i agree with Gerolf above : the button must be placed before the text, to be all time at the same place.
-
would be fine with a expand all for when its needed however if we decided to keep the old style being able to link to the return type and paramater types from the list of methods at the top of the page would be a useful additional feature
-
Would it be a good idea to have the possibility to also show the inherited methods in the overview in a nice way? It is easy to miss methods or signals that have been defined in base classes, and it would be nice if you could augment the current overview with them. Coolest would be if you could that step-by-step. For instance, if you are viewing the docs on QSslSocket, you could expand the docs like this:
QSslSocket specific stuff (default view)
add QTcpSocket specific methods (the ones not reimplemented by QSslSocket)
add QAbstractSocket specific methods (the ones not reimplemented by the above subclasses)
add QIODevice specific methods (the ones not reimplemented by the above subclasses)
finally add QObject methods.
Methods added to the docs from a baseclass, should probably be marked as such with an [Inherited from <ClassName>] kind of label.
-
A very good idea, Andre! I would appreciate this.
-
That's a great idea, Andre. I would be behind that 100%.
-
like the new way with few suggestions
- Like others said, expand button goes to the beginning of the line. Generally function names are of various character lengths. If we have expand button at the end, we may need to search for them.
- Do we need this line explanation for each method. Does it convey any useful information. If we remove it, its almost same as good old layout, and we gave expand buttons added at the beginning of each method / property.
- We need to have collapse all button readily available somewhere in each page. Otherwise we end up with same problem that we have now.
-
Seems that links inside the code blocks have some issues and the link url are visible. You can see the issue in for example http://developer.qt.nokia.com/doc/qt-4.7/qdeclarativeimageprovider.html
@<a href="qdeclarativeimageprovider.html">Image</a> { source: "image://myimageprovider/image.png" }@
Otherwise liking the new style docs.
-
Andre: I agree that inherited members should be displayed in a better way. Actually, they are now in the lists with the other class members, so they should be easy to find now. It can probably be done (with the current documentation XML source) in the way that you describe, but it will require a heavy reconstruction. It will be up to the web team to decide upon this. I’ll make sure to put it in the pile of requests. :)
Vijay: Thanks, we are testing different solutions right now. I’m including your input in the case. :)
timoph: Thanks, we have discovered a flaw in the syntax highlighter, so we will remove the links inside code snippets for now.
-
this new idea is nice and will reduce scrolling for quite a bit
the link to expand function definition is too small,
something like jiras road map would be easier to use with nice wide targetas long as you have easy accessible options for expand/collapse all
the browser text search won't be a problem
in most cases i don't believe that search through long description would be unnecessarywhat i would like to add are filters/sort by:
- function return type
- function arguments contain a type
- inherited from
-
few more comments...
-
Most of the qt function names are self explanatory, don't know how much benefit we get by adding one line description to them.
-
When a method is in expanded state, we can add "collapse all" button next to collapse button of the method
-
And there should be a global "collapse all" button available.
-
Along with #include for the header file, it would be nice to say if there is any qt module that needs to be included in .pro file. I have seen lot of posts in the internet complaining about compile time errors with out including needed qt modules in .pro file.
-