qml-box2d documentation

[folibis]

I guess we should think about API documentation for qml-box2d plugin. Сertainly, it's close enough to Box2D API just as plugin code is clearly but anyway ... At least we would comment all new code to make it readable for some appropriate tools like doxygen.

[bjorn]

@bobweaver has started work on documentation at https://github.com/bobweaver/qml-box2d/tree/qt5. I've asked him to open a pull request so we can discuss the changes he made.

[bobweaver]

Hello there I have been working REAL HARD on the docs/examples and they are
almost done. Rusian please take a minute to see how they where put
together. Also reading the TODO and README files wold not hurt, Doxygen
supports qdoc tags. But more important qhelpgenerator supports qdoc.
This is what all internal Qt classes use. If you also look at the
examples qdoc is also compatible with this. and also snippets.

I figure that I should have a real good fork of the code with docs snippets
and what not in a week or so.
But the framework for QML is Done. some of the Basic Elements still need
some work from my fork of the branch.

world
body
fixtures

most of the Joints are done.

The c++ classes need more work

if you run
qmake
make docs

You can see where some of the C++ classes are not documented.

let me know what I can do to make this better

thanks

Joseph Mills

On Tue, Mar 25, 2014 at 10:19 PM, Ruslan Mukhlynin <notifications@github.com

wrote:

Closed #13 #13.

Reply to this email directly or view it on GitHubhttps://github.com//issues/13
.

[folibis]

Really great work! As for me I am very impressed.
Descriptions, examples, now it looks as ...hmm, a ripe product.

May be we need some code style guide? Some "read before pull request" file?
To write code as close as possible to completed and documented sources.

[bobweaver]

Ruslan if you would like to write a text file I would be willing to make it
into a md & qdoc file for the "read before pull request"

and also integrate into the docs. Or if there is something already out
there I could integrate that also.

On Wed, Mar 26, 2014 at 5:56 AM, Ruslan Mukhlynin
notifications@github.comwrote:

Really great work! As for me I am very impressed.
Descriptions, examples, now it looks as ...hmm, a ripe product.

May be we need some code style guide? Some "read before pull request" file?
To write code as close as possible to completed and documented sources.

Reply to this email directly or view it on GitHubhttps://github.com//issues/13#issuecomment-38665781
.

[folibis]

I have a thought about our examples. Maybe we should take Box2D Testbed as example here?
I mean one application with ability to run qml files from examples tree? And may be with ability to view source code as nice addition.

[folibis]

I would be happy to write it but my English is too poor for this task (

[bobweaver]

Russian what is you primary language ?

Here are two screenshots
This one shows the ability to launch any of the examples.

http://imgur.com/4bp3zu0,JhNOzDn#0

I am installing the qml examples to / quick / box2d
one can run these and also look at the documentation for the examples
(after installing the qch docs).

http://imgur.com/4bp3zu0,JhNOzDn#1

Is this what you mean by TestBed ?

As far as coding style I can look at the src code and add some stuff. Will
alert you after that is done. maybe you could add more or give tips ect.

Thanks again for getting back to me.

Joseph

On Wed, Mar 26, 2014 at 6:10 AM, Ruslan Mukhlynin
notifications@github.comwrote:

I would be happy to write it but my English is too poor for this task (

Reply to this email directly or view it on GitHubhttps://github.com//issues/13#issuecomment-38666883
.

[bjorn]

@bobweaver Your changes are really nice, but I'm a little concerned about your git commits. There's a lot of things that went wrong there and I think some of your changes should be re-applied in a cleaner way. Examples:

• Commit 62d81d0 seems to be adding all the source code and examples and then commit d79deae removes them from their old location. This moving around of files should happen in a single commit (and separately from the adding of the doc folder). The first commit also adds a lot of .qmlproject files that seem to be later removed again in commit e5c592d. They should just not be added in the first place then.
• Commit f885ca8 accidentally adds a .autosave file, and then commit 5714fe8 removes it again among some unrelated changes. The first commit should be amended to not add that file instead.
• Commits f885ca8 and e75f4c9 have clearly misformatted commit messages and the latter is just removing a newline. Instead, whichever commit added monera.pro should be amended to not add the file with that double newline when this is undesired.
• Commit e2b7a9e added all of the generated HTML documentation while commit 9db1c9f removes it again. Same as above, the preferred way to go about this is to change the commit that added the files to not add them for the sake of a clean history. The first commit also mentions "changed a couple of imports in one of the example's", but I don't see any example being changed in that commit. Possibly the commit message needs adjustment.
• Commit a58114f added a build directory that was later removed again in commit c54539a.
• The merge d3ebdcd had a conflict but instead of resolving it the conflict marker was committed. Part of the conflict marker was then removed in 9136d0b (which deleted the README file that should instead be deleted together with the README.md addition in commit d7a86cd). Finally the conflict was resolved in commit 3f3dcf5 with a somewhat strange commit message.
• Commit 3a7b5ee added some unrelated gsourcemaker script.

Do you know how to use git to clean this up or have time to learn how to do it? If not I could help you by re-applying some of your changes manually.

[bobweaver]

Hey Bjorn

yes I am new to git. And thanks for the pointers so far, it has been
helpful !
From your Comments

1. I wrote a script that took code from one of my other projects and
   copied it over to the examples files. this is why there was so many
   qmlproject files

2. I have added some stuff to the git ignore file so that it will not
   include many of the files noted above.

3. I am not sure what you mean by amended. Like added to ? again I am new
   to git and do not know that much about it.

4. yeah II forgot the the html was in there when I pushed that I will try
   to look at the code more before I push.

5. see 4

6. again I am not sure how that works in git. Like removing files and what
   not.

7. gsource maker script was used to make a video about the development of
   the docs and the over all development of the bindings.

As far as using git I would love some help on cleaning up the branch that I
am using. I figured that I would use as a alphs or future-release branch
and push to the main branch after I was done with the frameworks and what
not for the docs.

the commands that I have been using after hacking are

git add -A
git commit -a -m "my message "
git push

I do not know the "fancy" commands yet.

Thanks again for helping with this and I would like all the help that I can
get with cleaning up the git log if that is even what it is called.

Joseph

On Wed, Mar 26, 2014 at 7:28 AM, Thorbjørn Lindeijer <
notifications@github.com> wrote:

@bobweaver https://github.com/bobweaver Your changes are really nice,
but I'm a little concerned about your git commits. There's a lot of things
that went wrong there and I think some of your changes should be re-applied
in a cleaner way. Examples:

• Commit 62d81d062d81d066c3021b9969440486a5d8bb8790a2c16seems to be adding all the source code and examples and then commit
  d79deaehttps://github.com/qml-box2d/qml-box2d/commit/d79deae2185e3a2ba9509c8bc17ff71335fa698aremoves them from their old location. This moving around of files should
  happen in a single commit (and separately from the adding of the doc
  folder). The first commit also adds a lot of .qmlproject files that
  seem to be later removed again in commit e5c592dhttps://github.com/qml-box2d/qml-box2d/commit/e5c592d3c9ed91683f3b2048b65d72f2a9bebd0e.
  They should just not be added in the first place then.
• Commit f885ca8f885ca8a49308c36ea1d02d1fc5ee11e1dfeb9adaccidentally adds a
  .autosave file, and then commit 5714fe85714fe8259925ab54d459e3382bb6ff18faa2e68removes it again among some unrelated changes. The first commit should be
  amended to not add that file instead.
• Commits f885ca8f885ca8a49308c36ea1d02d1fc5ee11e1dfeb9adand
  e75f4c9e75f4c9b07810ad29b62dc8f85ec651e1e7be618have clearly misformatted commit messages and the latter is just removing a
  newline. Instead, whichever commit added monera.pro should be amended
  to not add the file with that double newline when this is undesired.
• Commit e2b7a9ehttps://github.com/qml-box2d/qml-box2d/commit/e2b7a9ef3e9d48bc35d8365a1d6810ef1e9550f3added all of the generated HTML documentation while commit
  9db1c9fhttps://github.com/qml-box2d/qml-box2d/commit/9db1c9f4ea1ee5bc5533d20da8229a2e636b8fa1removes it again. Same as above, the preferred way to go about this is to
  change the commit that added the files to not add them for the sake of a
  clean history. The first commit also mentions "changed a couple of imports
  in one of the example's", but I don't see any example being changed in that
  commit. Possibly the commit message needs adjustment.
• Commit a58114fhttps://github.com/qml-box2d/qml-box2d/commit/a58114f03c941526f31afe4139a5b97c1bf0eea7added a
  build directory that was later removed again in commit c54539ahttps://github.com/qml-box2d/qml-box2d/commit/c54539a04ba0c8e2681e08bcb312299a61308d47
  .
• The merge d3ebdcd had a conflict
  but instead of resolving it the conflict marker was committed. Part of the
  conflict marker was then removed in
  9136d0b (which deleted the README file
  that should instead be deleted together with the README.md addition in
  commit d7a86cd). Finally the conflict was
  resolved in commit 3f3dcf5 with a somewhat
  strange commit message.
• Commit 3a7b5ee added some unrelated
  gsourcemaker script.

Do you know how to use git to clean this up or have time to learn how to
do it? If not I could help you by re-applying some of your changes manually.

Reply to this email directly or view it on GitHubhttps://github.com//issues/13#issuecomment-38672964
.

[bjorn]

Ok, first of all about the commands you're using:

git add -A

This is a useful but dangerous command, since it will add any untracked files. Before you do this you should always do git status and check whether all those untracked files are indeed files you want to add. If not, add files either one at a time or by directory by running git add <file/directory> until the files you wanted to commit are added instead of using -A.

git commit -a -m "my message"

Again, this is useful but dangerous because it will commit all changes you've made regardless of whether they're actually relevant to the commit you're trying to make or whether they were related to something else or temporary changes. Usually a much better approach is again to use git status to see which files you changed, and add files to the index either individually or by directory. Personally I always use git gui (or git citool for a GUI meant only for creating a commit) so that I can pick changes to include in the commit by hunk or even by line and type the commit message as I go. I can only recommend it.

I am not sure what you mean by amended.

Amending a commit means changing it in some way. You can amend a commit to add files, remove files or change its message, timestamp or author. Basically you would stage your change as usual, but then instead of doing git commit you would do git commit --amend, and it will include the staged changes in your previous commit instead of creating a new commit as well as prompting you to edit the existing commit message. You can do the same thing visually with git citool --amend (or switch between these two using the radio buttons above the commit message field).

Now, amending only works on the last commit you did. When you want to amend a commit you did earlier, you would first need to bring your current state back to just after that commit, and then you would need to rebase all the commits that followed onto the amended version of the commit. The easiest way to do this is by using an interactive rebase, but I urge you to read up on that and also to read closely what git tells you while you do it. If you don't follow its instructions carefully you can end up in a big mess from which it can be hard to recover. A good start may be to read http://git-scm.com/book/en/Git-Tools-Rewriting-History.

Let me know how it goes and feel free to ask for help.

[bjorn]

@bobweaver Any luck with this?

[bobweaver]

Hey there Sorry I have been real busy in RL with many different things. I am going to give it a shot again. I think that I now have a better understanding of Git. So things should go a smoother. Or at least I hope.

[bjorn]

@bobweaver So did you have any time to work on this and if so, how are things going now? I don't mean to put any pressure, I'm just looking forward to see this move forward.

Note that also the Bacon2D project has integrated qml-box2d and they did already write quite some documentation, which is probably worth integrating back.