Documentation wishlist

[pekka]

EDIT: Check the Wiki for the latest doc updates. I am not updating this posting anymore.

I am currently working on putting up the pages for functions in LÖVE 0.6.1 that are not yet documented at all. I still have several to go, and you could help me. I am going to list all the functions that do not have a page at all at this moment, as links to the Wiki. If you follow them while being logged on to the Wiki, it offers you a change to open the editing screen which allows you to add the function in there. If you feel you can write a simple description of any of the functions below, please go ahead and do so. Please do also make sure I have not made a mistake, and only document functions that actually exist and are spelled correctly!

Also, be sure to read the editing guidelines in the Wiki first.


When all the missing functions are in there, we can think about what other ways we have of improving the documentation. If anyone has any wishes, you can voice them in this thread. Or, you can go over to the Wiki and use the talk pages to tell us what could be better, and what should be clearer. If you are capable, simply edit the pages and write a better explanation yourself. Writing better docs is a long process, but it helps if you, as a user of the docs, tell us what are the best ways to improve them.

EDIT: Two functions removed, as Bartbes confirmed they don't need to be documented. They are not meant to be used from Lua side.

Here are the rest, grouped somewhat by category.

http://love2d.org/wiki/love.graphics.reset

http://love2d.org/wiki/SpriteBatch:lock
http://love2d.org/wiki/SpriteBatch:unlock

http://love2d.org/wiki/ParticleSystem:getOffsetX
http://love2d.org/wiki/ParticleSystem:getOffsetY
http://love2d.org/wiki/ParticleSystem:setOffset
http://love2d.org/wiki/ParticleSystem:s ... eDirection

http://love2d.org/wiki/Body:setFixedRotation
http://love2d.org/wiki/Body:setInertia

http://love2d.org/wiki/CircleShape:getLocalCenter
http://love2d.org/wiki/CircleShape:getWorldCenter

http://love2d.org/wiki/DistanceJoint:setDamping

http://love2d.org/wiki/PolygonShape:getPoints

http://love2d.org/wiki/Shape:getGroupIndex
http://love2d.org/wiki/Shape:setGroupIndex


EDIT: I've inserted a note to the three functions below saying that they are or may not be usable, because they are not in the Lua binding. I've checked that they are not usable in the version I have.

If getMaskBits is going away for good, the page should probably be removed. I've left it there for now.

http://love2d.org/wiki/DistanceJoint:setDampingRatio
http://love2d.org/wiki/Shape:getBody
http://love2d.org/wiki/Shape:getMaskBits


I will edit this posting and remove pages that are added. Any corrections are welcome if I have made a mistake or omitted something.

[bartbes]

http://love2d.org/wiki/Shape:getMaskBits

I happen to know this was removed (it was in.. 0.5.0 I think), it might be that the C++ code just happened to persist, or is used internally.

http://love2d.org/wiki/.DistanceJoint:setDamping

What is that dot doing there?

Right, here are two ones that I suppose do not need to be documented, as they are meant for testing and internal use respectively. What do the devs say? Shall we skip these?

I'd say we keep them undocumented.

[pekka]

I removed the unnecessary functions and fixed the errant dot. It was a copypasta error.

I am not sure I saw getMaskBits in the source, actually. It's in the above list because it is in the documentation. I am going to put some words on its page now to the effect that is has been removed. I'll leave the decision to remove the page to someone else for now.

[pekka]

While adding some joint constructors to the docs I noticed not all the methods for all joints are documented beyond just listing that they exist. Some of them don't even have the parameters they accept. Oh well, more work to do.

The physics documentation can be rather incomprehensible at this point. I hope to fix this by writing some new tutorials or improving the current ones later, and my first goal is to just get them all documented with all the parameters properly explained. Please have some patience! You should eventually be able to learn how to use the physics module much more easily that what is currently possible...

[pekka]

I put up a list of pages I am hoping to write eventually on my Wiki user page. I'll add some of the nearly empty physics module methods there later, and will probably continue writing next weekend.

I'll leave the original posting up, since the list there might be useful to someone. I will not update this thread anymore, though. The Wiki can be used to talk about the docs.

[kikito]

Pekka, I just wanted to say again that I appreciate your work a lot.

Thank you

[pekka]

I appreciate your comment, Kikito, and I really just hope I've done something useful. There's more we can do to make LÖVE better documented and easier to pick up for new people, and we all can chip in on this in the Wiki and the Forum. Don't hesitate to do your part, everyone!

There is now a Wiki page that lists a few functions I have chosen not to document yet for a variety of reasons. http://love2d.org/wiki/Missing_Documentation

(I will list some of the things I wonder about them in the Discussion page after I post this message.)

I hope others will keep an eye on the state of the documentation and update the appropriate pages whe new versions of LÖVE come out. I'll try to do it too, but I may not always have the time. Cheers.

(Now I am going to write some code for a change )