Documentation is pretty, bland.

[JSharpe]

So i thought i might give LOVE a try, though the documentation is pretty bland and empty.

Compared to other Wiki's and Documentation I've seen, I'd have thought to see a lot more detail in how to use functions within LOVE. I always read through the wiki briefly to study how I should code a game in the environment.

Take for example this;

http://love2d.org/docs/love_graphics_setColor_2.html When i first looked at it, I was thinking, set the colour of what? Can i change colours of images with this, maybe an object i created? How am i meant to use it at all?

Is it not possible to add in information about functions and elaborate on how they work, where they should be running? Maybe move the whole documentation over to the wiki side for the community to edit and place in examples of efficient, effective code.

An example of what I'd like to see (information wise) is this; http://wiki.garrysmod.com/?title=Entity.SetColor

Compaired to the LOVE documentation on SetColor there's a lot more information on how it should be used.

I asked in IRC and they seem to agree with my point of view.

[qubodup]

I also now think that the documentation should be wiki-ish.

Does anyone want to suggest a documentation system, that makes it possible for guests to submit alternative versions of pages and that makes it *easy* for the admins to accept/decline these suggestions? (Easy as in not having to copy-paste anything, simply click yes or noes.)? Perhaps it would suit them developer dudes.

[Pliskin09]

nope, but should not be too difficult to write up

[Robin]

I agree with the OP.

qubodup: why not just use the wiki?

[Pliskin09]

to be honest i find it very hard to find stuff on that wiki. theres no where to get you started and you need to know what to search for before you get anything to come up. (unlike with the documentation area, where everything is very easy to find. )

[Robin]

to be honest i find it very hard to find stuff on that wiki. theres no where to get you started and you need to know what to search for before you get anything to come up.

Which can be changed. It's a wiki! I'd do it myself, right now, but I'm on a rather tight schedule this summer. Any volunteers?

[Arthurio]

I wholeheartedly support this. The current documentation is lacking to say the least.
Imo there should be:
1) more info about parameters: min and max values, default values, maybe tips
2) more info about what a particular function or method does
3) examples!! and links to examples! with code, screenshots and .love!

Lets just use the wiki, don't be afraid of your users, assign mods.
Anyway I'm willing to contribute with however little I may have.

[rude]

Using the wiki or any existing wiki systems I know of is out of the question. It would involve a maintenance nightmare we do not have the capacity to solve. It would have to be a new smarter system. If you add a function, for instance, it should automatically appear in relevant pages, such as the list of functions in the parent. Another example is a subclass: it should be enough to state that a class is a subclass of another class, and functions from the superclass should appear automatically in the function listing of the subclass. If a system like this already exists, please let me know.

As qubodup says, changes should be approved by a developer before it's released, so there's at least a chance the information in the documentation is correct.

(OP: I must say your link to Entity.SetColor made me laugh, as it was a decent example of why documentation should not be wikified. It has worthless listing of "information" like "first value is red", and the example had lots of irrelevant code. )

[Robin]

Maybe. But I'm still in favour of adding more extra and detailed information to the wiki.

And as for that "new smarter system": what you say about that reminds me of Doxygen. I've never used it myself, so I don't know if it can do all that.

[JSharpe]

(OP: I must say your link to Entity.SetColor made me laugh, as it was a decent example of why documentation should not be wikified. It has worthless listing of "information" like "first value is red", and the example had lots of irrelevant code. )

Yes that example i posted shows some information that is not necessarily needed or connected to the function.

Though i'd prefer seeing that than looking at this; http://love2d.org/docs/love_graphics_ne ... ont_1.html and thinking how I am going to pass on a glyphs,

Should i do them like this;

Code: Select all

"ABCDEFG"
"A B C D E F G"
chars = {"a", "A", "b", "B", "c", "C"}

There's no information about it.


Another example is http://love2d.org/docs/ConfigFiles.html

I was stuck for 20 minutes thinking what was wrong with my test code. Only to have to look at some one elses work, then find out that "love_version" had to be set as a string. A silly mistake because the documentation didn't have enough information. Just adding in square brackets next to it [string] or [int] and what ever other types there are would have stopped it.