Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Need skimmable index per class #282

Open
keyframer opened this issue Feb 21, 2021 · 4 comments
Open

Need skimmable index per class #282

keyframer opened this issue Feb 21, 2021 · 4 comments

Comments

@keyframer
Copy link

I'm new to Haxe (and it's related projects) so I've been using the output of this tool extensively! All of these pages desperately need an index of all properties/methods. It is very hard to browse classes and get a sense of what they do.

Like here, what kind of things can you do with an array?
Or on Haxe Flixel, what's covered by their Math utilities?
You have to wade through all the hairy details! I just want to skim for what looks familiar or new.

Most API docs present information like this, but see Qt for one of many examples:
https://doc.qt.io/qt-5/qaction.html
You just skim this index to see if you're in the right place than click the method that looks ballpark and start reading descriptions.

Another great thing on the Qt docs is the "List of all members, including inherited members" link for any class.

Thanks for considering!

@Simn
Copy link
Member

Simn commented Feb 21, 2021

I actually don't like these redundant overviews very much... It would be fine to have a simple list of field/method names in the navigation on the left, but I don't want to duplicate everything in the main content.

@Aurel300
Copy link
Member

I think I agree with OP here. Assuming a class is properly documented (as in, each method has some amount of docs), scrolling through the document to find any particular method might take a minute. A summary at the beginning which only links to the methods is useful. If it were in the navigation on the left, this would not be very readable IMO.

@Gama11
Copy link
Member

Gama11 commented Feb 21, 2021

There could simply be a button that collapses / expands the doc comments.

@keyframer
Copy link
Author

Right having the index be part of the sidebar hierarchy is a totally reasonable place to put this.

Microsoft docs do exactly that:
https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1.add?view=net-5.0

Of course their docs are so extensive you have to navigate with an index like this:
https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.list-1?view=net-5.0#methods
It would be totally unreasonable to inline every method on a single page.

You might also get a bonus feature by including the index in the side hierarchy: you could filter for method/property names using the filter at the top left. I actually kept trying to use that filter for this purpose, since there is no other search on these pages.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants