Synfig Studio - Documentation and Organization

When I began working with Synfig Studio, I found it difficult to understand the code and implement new features. These past few days I went through the code file-by-file, hoping to come up with some refactoring changes to make it simpler. Instead, everything turned out to be perfectly logical: the difficulties arose chiefly from lack of documentation.

I propose that we go through the code, making the following improvements:

  • Documentation - There should, at the very least, be a description for every class
  • Reorganization - I think it’s a good idea to split up the code into subfolders
  • Rethink confusing names and terminology - like “smach”, “RendDesc”, and “framedial”
  • Clean up large blocks of commented-out code - explain why the code was commented out, or delete it

I’ve made a rough list of the files in the order I think of them in my mind: http://pastebin.com/LrdkJc4q An actual reorganization should, of course, be based on different criteria. I can begin by suggesting the following changes

  • rename the dials (framedial, zoomdial, etc) to share a common prefix
  • about, canvasoptions, canvasproperties are dialogs - name them accordingly
  • move rotate out of the module; make draw tool a module instead

Great work on the pastebin. I agree most of the suggestions but why to include Draw into a module? I know that pen pressure is something optional but I don’t understand why it should be in a module? With or without pen pressure I would like to be able to use the Draw tool.

-G

Draw module was mostly a spontaneous decision. My logic went something like this: we need a tool in a module to act as a code sample of how it’s done, and draw tool works the worst. In addition, it uses a separate class currently located in synfigapp, but the two should best be in the same folder.

Pretty subjective. I’m willing to go either way.

Now as for the actual structure, I think we should discuss it in detail sometime. This should be a group decision, but I don’t know if any other people interested in making suggestions.

This is great - any reason why not to include on the wiki?

You had a question mark next to IPC - I suspect it stands for inter-process communication - thread handling. Haven’t looked at that code - does that context make sense?

en.wikipedia.org/wiki/Inter-proc … munication

Chris

That’s exactly what needs to be done within the core too.
In the core, I suggest to split the synfig-core folder into libsynfig and synfig-tool (or synfig-cli which I like more) which are both two separate build targets.
The modules should also go inside libsynfig, not outside as they now are, and some headers should be exported to the include directory so the parameters for renderers (as needed for ffmpeg, now isn’t done in a proper way) can be seen by the applications.

In studio we also have an application library and then the UI code but I don’t know if they are independent enough to put them in separate folders, as the different build targets that they are. For example to have a Qt interface, if somebody ever wanted to do it, using the same app library.

I’d be glad to help in reorganization and documentation, although I still don’t have much knowledge about how the code works, but I’ll do my best.

For your question in pastebin, RendDesc is a rendering description. It contains the basic parameters for the rendering modules. Additionally I added targetparam which is used for extra parameters like the needed for ffmpeg.
Now it’s similar to RendDesc, contains some fields, but it’s not intended to be like that but a base class, inherited in the modules in which is expanded to the needed parameters, but for that we need to change the modules organization for the headers to be exported so they can be seen by both the tool and the studio and I don’t know enough about autotools yet.

pixelgeek:
I don’t think that my rough notes belong in the wiki. Rather, I suggest using Doxygen to generate our developer documentation.

eldruin:
Thank you for the comments on RendDesc. In reality, I have only a cursory knowledge of the renderer because it is arguably the most complex part of the application, and I have decided to first master the other components of Synfig.

I wholly agree that synfig core could use the same improvements as studio. However, there is at least one active branch (opengl) that is based on the current code, and I believe it would be a good idea to merge it before proceeding with changes in code structure.
Unfortunately, I have not been able to successfully run that branch: opengl shader init causes a segfault, most likely because my driver only supports opengl 1.4. Then again, blender manages to run without problems.

So what I’m suggesting is that we not push ourselves too far and start with just Synfig Studio. I think it’s a more realistic goal, for the short term.

EDIT:
I’ve noticed that while our files mainly use tabs, some lines have spaces instead. I think we should decide on one as the default and convert all of the code accordingly.

OK: my two suggestions for the new code structure. I very much prefer the second one.
http://pastebin.com/yiJXdhQc
http://pastebin.com/w5iyUeck

I still need to look into the sound and cellrenderer code, but for the most part I understand what is going on in the code.
Please give me some feedback here: should I revise the structure some more, go ahead with modifying the code, or scrap the idea altogether?

EDIT: I have some idea of what the cellrenderers do now. And this adds another file (cellrenderer_gradient) that never appears to be used - cellrenderer_value is employed instead.

EDIT2: The wiki links from inside synfig are no longer valid now that we have switched hosts

Only that would be a great improvement!

Me too.

I’m aware of that. I’ll fix them.

Go ahead. But remember that I won’t include it on the master branch until we are sure we can build it in any platform (windows included) and that all functionality is kept. Believe me, when moving code between folders, not only a modification in the #include is needed. I bet that configure.ac and m4 macros will be modified so this is not a trivial modification.
Try to merge the current master into your branch from time to time to avoid long conflicts when merge so late.
I’ll continue doing the needed modifications for the new release.
Cheers!!!
-G

I think I’m nearly done with restructuring. The build system for the c++ works, but I’ll need to update the po files. Dunno why they don’t automatically get built along with the application; perhaps it’s because I’m in debug mode.

The only major thing left to do is decide on a naming convention: do we want names like “states/state_bline.cpp”, “state/state_bline.cpp”, “states/bline.cpp” or “state/bline.cpp”. What do you think?

After that it’s just documentation. In fact, I may even meet the upcoming feature freeze deadline if you think we ought to include the changes in the next release. (These changes have little or no effect on the application’s functionality/stability)

Any of the name scheme are fine to me, maybe the first one is my preferred: “states/state_bline.cpp”. It is longer but I don’t want files

Regarding to include into the new release I still thinking that we should postpone after the release. Changing the folder scheme implies lot of work for old branches (specially opengl) so I prefer to start from a stable version to do that. Also there is not new features so there is not hurry to include it. I prefer a clean release.

-G

The release is out now so we have green light for those changes, are working on those proposed changes? Do you need help or are waiting for any commitment from the Synfig Team?
I’m working now on Synfig Core for a similar task.
-G

The structure is mostly set at this point, though there are a few minor things that still need to be done. You can try looking at the way the code is placed right now and see if there’s anything that doesn’t make sense. Documentation is the next step; I’m going to try to motivate myself to do that sometime soon.

Come on! I’ve been seeing A LOT of activity in the repository. That’s the way :slight_smile: I hope I can start working on some code again soon :slight_smile:
Keep it up guys!

Genete deserves all the praise here. I haven’t done a thing in ages. But I hope that (just like you) I can start working again - as soon as I catch up with all the changes that have been made.