Documentation sucks

[barbushin]

Such a great project, and such a... documentation :(

Examples are mostly about editing, but I think 90% uses this library for XML/HTML reading & parsing.

Check out some examples of good documentation:

https://github.com/barbushin/php-console https://github.com/barbushin/dater

[technosophos]

You are more than welcome to contribute to documentation!

The QuickStart Guide may be a little too quick. Certainly it'd be good to add to that, and maybe link to it from the README: https://github.com/technosophos/querypath/blob/master/quickstart-guide.md

Most of the examples were written a few years ago, and I'm sure could use updating: https://github.com/technosophos/querypath/tree/master/examples

The Tutorials are definitely old: https://github.com/technosophos/querypath/tree/master/tutorials

The main API docs site is definitely dated: http://api.querypath.org/

Finally, http://querypath.org/ source code is here, if you want to look at that: https://github.com/technosophos/QueryPath-WWW

[barbushin]

Yes, thank you. But I'm just saying that library is written in very old style, I mean IDE autocomplete in many cases not works, so the only things to get answer is documentation.

And because of bad documentation, I just can't use it :( It took too much time to find the answers, so I just remove it, and continued parsing HTML using regexp...

I wish to contribute, but I have too much things to do with my own open-source projects.

I hope some day I'll get back to QueryPath refactored in more modern way and having good documentation.

[technosophos]

Oh. Your issue said the documentation sucks, and didn't say anything about IDE autocompletion. I didn't know that was a problem. If you could open an issue describing that, I could work on it. Earlier this week I fixed one bug related to that.

And now I'm confused about what you mean by "bad documentation". What, particularly, were you looking for that you cannot find? I just pointed you to a few dozen documents... but you haven't said what in those was missing, what you'd like to see, or how you would suggest making things better. An all you pointed me to was your own projects. Everyone thinks their own documentation is good enough.

When you said "90% of uses this library... [for] reading & parsing", I don't know what you found lacking. QueryPath parses the document (and reads it) in one single call, which is documented all over the place. It's just qp() or htmlqp() to read and parse.

Overall, I'm just really confused about what your initial issue was for.

[barbushin]

Just a small example of IDE autocompletion problem: http://i.imgur.com/dE5V0Dd.png

There are a lot of ways how to annotate code to help IDE autocomplete. Like

@return SomeClass|SomeClass2 - if method return different classes objects @return SomeClass[] - if method returns array of some class objects @return self - if method return own class instance

and etc.

Talking about what exactly questions I have about QP usage - there is a lot of questions, and I see it's possible to find the answer using links that you gave. But it's just took too much time :(

[technosophos]

Ah! I see! Your IDE is using annotations to do autocompletion.

The syntax for @return is dictated by the documentation engine, which in QueryPath's case is Doxygen (not PHPDocumentor, unfortunately). Doxygen uses @retval and @return differently than PHPDocumentor. We use @retval throughout QueryPath, and it sounds like your IDE does not support that. We've looked at switching from Doxygen to PHPDocumentor, but it's actually a HUGE task. There are a lot of subtle differences, and there's no real way to test.

Can you tell me what IDE you use so I can look at its documentation?

But that's a different issue. For this present issue... I still don't have a clear idea of what you think ought to be changed. Would more links in the README help? Obviously, I can't include every use case or even every method on the main page. But I sure could link to other places. Would that help?

[barbushin]

I use PhpStorm. I think it's most popular IDE for professional PHP programmers. And actually I don't think that autogenerated documentation is so really needed. I think this is very "old school" way to document the project.

For me the best documentation is a some mix of methods list grouped by use case + code examples. PhpDoc annotations is 100% enough to document classes and methods, and GitHub markup is perfect for writing easy to read and understand docs.

And one more thing I want recommend you: do full migration from code.google.com to github.com. Before all my projects was on code.google.com and there was not so much contribution and population, but then I just migrated to github. And now when I see some project on code.google.com I just think that it's just very old and was not updated for long time.

[technosophos]

I'm going to try to migrate to PHPDocumentor. I referenced you on a ticket so you could see the progress.

[barbushin]

That's great! Thanks a lot, I'm happy to see QueryPath is on active development stage. That's :+1: !