News:

Simutrans Tools
Know our tools that can help you to create add-ons, install and customize Simutrans.

German in the code

Started by felo, March 10, 2010, 05:48:22 PM

Previous topic - Next topic

0 Members and 2 Guests are viewing this topic.

eipi

Quote from: whoami on May 30, 2012, 07:09:04 PM
@Eipi: since you work on the comments, your changes and mine are the ideal complement to each other, yours to be applied first. Do you keep this in sync with the ongoing development?

Yes, I try to, if I have time. My plan was  to get finished with the translation until the end of the year, maybe a bit sooner. However, progress is slow as I am no expert with the code and if anybody spots an error, feel free to notify me of them. :)

whoami

#106
Quote from: Dwachs on June 06, 2012, 07:15:25 PM
What is the point in renaming get_count to get_count_ first?
Both get_count and get_anzahl exist in the original files, same with many others (as said). I assume that the English ones of these pairs were introduced later and are therefore used in a narrower context and in lower numbers. I plan to look up all the conflicting English ones (file for phase1, perhaps 100 names in the end) and find more specific names for their context and use, but currently, I just move them out of the way with the appended "_".

QuoteYou should also adjust the usage-comment, the command is check not checkall.
The usage comment had more outdated information, I have changed it.

QuoteNow I do not know how to proceed.
Have you run phase2?

QuoteTranslating all the code at once seems to be not sensible.
Phase2 can be split by splitting the translation table, e.g. between classes or files.

QuoteI do not want to end up with names with trailing underscores.
(Some of these exist already in the code.) The problem is: if I ignore and allow the potential conflict from naming two things the same, I cannot guarantee that there are no actual, undesirable name clashes, leading to overridden variables or class members. I hope that I get rid of the trailing _ in phase1, instead of writing a single-use code monster (parser and some semantics) which might take months to complete (and then be rejected for actual use because it's not understandable by anyone, including me).

I looked for professional tools: MSVS 2010 seems to be available only as time-limited trial (nowadays), not as express edition, and tools like Visual Assist (which should do C++ refactoring) do not support the latter anyway. So I will stick with VS 2008.

Markohs

Quote from: whoami on June 06, 2012, 07:58:10 PM
I looked for professional tools: MSVS 2010 seems to be available only as time-limited trial (nowadays), not as express edition, and tools like Visual Assist (which should do C++ refactoring) do not support the latter anyway. So I will stick with VS 2008.

http://www.microsoft.com/visualstudio/en-us/products/2010-editions/express here, down the page, you can download the visual studio 2010 suites, (for example the C++ http://www.microsoft.com/visualstudio/en-us/products/2010-editions/visual-cpp-express) . They are free, complete compilers, hurry up before they delete the 2010 version forever, since looks like they want all to migrate to 2012. :)

Vonjo

Sadly, there will be no Visual C++ 2012 Express. :(

whoami

OK, so M$ did not remove the download from all sites, but I can only see a web installer. Once they decide to not distribute it any more, I cannot reinstall it. But it's "free" as in "we lend it to you with no rent".

I installed VS2010 Pro Trial in a VM to use VA (or something else) with it, but I guess that the trial/evaluation license would not allow me to distribute the results to the public.

(BTW, I remembered too late that I use Unix tools on Windows in tr.cmd - just replace those calls, e.g. "tee" by ">>" redirection.)

Could this be moved to a developer board to (perhaps) get more feedback? I would like to know whether I should continue with the current approach.

Markohs

there is also iso images on the link I posted iirc

jamespetts

According to Microsoft, Visual Studio 2010 Express will remain available for download even after the release of Visual Studio 2012.
Download Simutrans-Extended.

Want to help with development? See here for things to do for coding, and here for information on how to make graphics/objects.

Follow Simutrans-Extended on Facebook.

Fabio

Is larger projects a suitable board?

whoami

The root development board will fit best, I think.

I would call this a technical conversion and not a large project, although the resulting .diff could have twice the size of the entire source code. :)

Fabio

Actually, there's no development board. There's patches board, but there it would be drowned among scores of threads. Larger projects was created to single complex projects which development can last long time.

whoami

I won't mind if it goes into "Patches & Projects", but "Larger Projects" may be a better choice, as this is not going to happen fast in any case: even if the method is accepted, there is still much to be discussed what to translate how.

Fabio


eipi

@Fabio: Thanks for moving! In my opinion this thread fits best in "Larger projects" now.

My comment translation is progressing. What has been done up until now:


  • Doxygen comments for nearly all previously documented methods except for most of the GUI code. I might have overlooked some, though.  :)
  • A few comments have been translated, too.
  • The files in ./bauer are finished totally, I guess.
  • I added a doxyfile in ./documentation which generates only HTML output.

the patch file against r5773 is here:
https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation.patch

(Already > 22k lines and haven't really started yet :o )

Dwachs

Impressive and most usefull! Will check this later.

Did you find any methods etc that could be deleted or moved to a different class (to provide cleaner interfaces) ?

I have also a patch to document some unimportant files (powernet and zeiger).
Parsley, sage, rosemary, and maggikraut.

Markohs

Good work!

Just having it a quick look, I think I spotted some errors:

* you are removing the documentation in *fabrikbauer_t::get_random_consumer
* triple empty line separating fabrikbauer_t::alles_geladen and  fabrikbauer_t::finde_anzahl_hersteller (line 247, should be just 2 empty lines, this happens everywere)
* removing doc at *fabrikbauer_t::finde_hersteller

eipi

Quote from: Markohs on June 14, 2012, 07:49:36 AM
triple empty line separating fabrikbauer_t::alles_geladen and  fabrikbauer_t::finde_anzahl_hersteller (line 247, should be just 2 empty lines, this happens everywere)

Ah ok, didn't know that there should be only 2 lines between methods. Fixed now.

I saw that some methods (like fabrikbauer_t::get_random_consumer()) had comments in both header and source files so I moved them to the header file to keep it all in one place. There might be some lines that haven't made it so I'll check that again.

Quote from: Dwachs on June 14, 2012, 06:26:38 AM
Did you find any methods etc that could be deleted or moved to a different class (to provide cleaner interfaces) ?

I haven't had time to dig into that, I am just trying to get an overview of the code while doing the documentation so this has to wait a bit.

Dwachs

According to Doxygen manual @return and @returns are both available, so there is no point in chaning one to the other type.

I will check and commit your stuff piece by piece if the next release is out :)
Parsley, sage, rosemary, and maggikraut.

prissi

Stupid question: Is there a simple tool to keep both comment in header and in cc in sync? The reason is that many private or seldom called functions functions are rather better documented there since they are only called from teh same module

Also only comments in a function but not clue on top what it does is also strange. (Personally, I would rather prefer the implementation with the documentation, but aparently the community voted otherwise.)

Dwachs

Iirc it is perfectly possible to have the documentation near the implementation, I think doxygen can still generate correct documentation out of it.

We need to agree on one particular style.
Parsley, sage, rosemary, and maggikraut.

Ters

When I have used Doxygen, which isn't often, I have put the documentation near the implementation. There are two reasons for this:

       
  • When you change the implementation and need to update the documentation, the documentation is right there.
  • I like to keep the header files minimal so that I can easily glance over them. Smaller header files are also probably faster to include in other files.

Markohs

Documenting just the includes has one advantage, I think, so the IDE can show the function documentation when you hover over it, as you are typing the code. I'd prefer personally document the headers, but as you already said, we just need to agree in a single way of doing it and just do it, on code or on includes, but just a single decision.

Ters

As long as the source files are avaiable, the IDE should in theory be able to show the documentation either way. For libraries, especially closed source ones, documenting the headers would be the only solution, but that's not the case here.

prissi

Unfourtunately I did not found out how to do this in MSVC.

And it really depends: For trivial functions, documenation of the header is certainly ok. But for more complex function, this is not enough imho. And then things get tricky with virtual functions. In principle only the "original" should be then documented.

Markohs

#128
for msvc to pick the comments in the includes, the syntax is sightly different, but it's compatible with doxygen I think:    /*!    \brief        Convenience function that creates the required objects to initialise the        CEGUI system.        The created Renderer will use the current OpenGL viewport as it's        default surface size.        This will create and initialise the following objects for you:        - CEGUI::OpenGLRenderer        - CEGUI::DefaultResourceProvider        - CEGUI::System    \param display_size        Size object describing the initial display resolution.    \param tt_type        Specifies one of the TextureTargetType enumerated values indicating the        desired TextureTarget type to be used.  Defaults to TTT_AUTO.    \return        Reference to the CEGUI::OpenGLRenderer object that was created.    */    static OpenGLRenderer& bootstrapSystem(const Size& display_size,                                  const TextureTargetType tt_type = TTT_AUTO); EDIT: According to this, that's the QT-style, msvc 2010 at least, sopports that style I think. EDIT2: Microsoft points us to XML documentation for this, but in my oppinion it's too verbose, and I'd stick with doxygen instead. Link.

EDIT3: mmm... All the information I posted i'ts not true, looks like you either use XML documentation in MSVC, or you document doxygen style, and use it to generate a .xml for Intellisense, having it a look.

Markohs

After spending some hours trying to get intelisense to work, I've failed, the only way of making it work is using XML style documentation, that uses something similar to:


/// <summary>
/// This functions documentation
/// </summary>
/// <param name="aa">blablabla</param>
/// <returns></returns>
bool function1(TypeX aa);


Looks like this style it's also accepted by Doxygen, and it's automatically processed and shown by Visual Studio Intellisense.

I see it one advantage over:

/*!
* blablabla
* \param
*/


And that's that you can comment entire sections of code, because you won't have a '*/' in the middle of the code.

Anyway I don't personally like it, I'd suggest:

* Use doxygen as the generator of the documentation
* Make header (.h) documentation mandatory
* Make code (.cc) documentation optional, only if extends the meaning
* Use:


/*!
* Doc
* \param a explanation
* \param b explanation
* \return explanation
*/

That information must be mandatory, any new method *HAS* to be docuemnted, and one can't touch a function already in code and leave it undocumented.

And for ocasional extra explanations in-code, use ///

I'd stick the documentations in the .h because it looks more natural to me, but said this, I don't mind if we agree in documentating just the .cc. But I'd like to reach one decision and see all the code documented the same way. :)

Dwachs

I would propose to document classes, their member variables and inline member functions in header files. All other functions should be documented in code, to get the code comments as close as possible to the implementation.
Parsley, sage, rosemary, and maggikraut.

eipi

#131
I'd also vote for documenting the headers because you can get a quick overview of what the classes and their functions are doing. If you just want to have a short header file, you could collapse the comments in MSVC / Eclipse / whatever so that they cover a single line only.
However, there will be some comments left in source files documenting static functions or global variables (unless we move their functionality to class methods in the future, of course).

EDIT:

@Dwachs: I know both @return and @returns are valid Doxygen syntax, but Eclipse does not highlight @returns and some other methods were tagged with @return, so I chose this :)

Markohs

 I still think just documenting the includes and just documenting the .cc in things that can't be documented in the .h it's the best option.

But if Dwachs proposition is chosen, given he menctioned documenting inline functions in the .h, I'll add another clause:

* Virtual methods of classes need to be documented in the super-class .h, and re-documentated in each .cc redefinition.

whoami

Concerning my tool (which is something like a quick hack or prototype): I had little time recently, so not much has changed, and I have only partially evaluated the alternatives.

But I also hesitate to continue, because - with the sparse feedback - I do not know how the chances are that it might be used, or what has to be added, improved or even removed to gain approval. From reading this whole thread, I know many of the requirements that exist for the task, though. If there is already sufficient reason to say "stop, this will not work out", please do, I have not spent very much time on it yet.

Markohs

My personal oppinion is that this project should continue, but it's up to prissi/Dwachs to say the last word imho.

About the documentation decisions we are taking, don't you think it's time to incorporate them to documentation/coding_styles.txt? looks like dwachs is already applying it in the code from what I just saw on last svn commits. I can make a draft if you want.

Dwachs

Quote from: Markohs on June 21, 2012, 10:40:49 PM
About the documentation decisions we are taking, don't you think it's time to incorporate them to documentation/coding_styles.txt? looks like dwachs is already applying it in the code from what I just saw on last svn commits. I can make a draft if you want.
Please go ahead :)

It would also be a good idea to come up with a nice header comment like "this file is part of simutrans project under this license see file bla" and make such headers consistent across files ...

@whoami: I am still undecided what to do. I see two interwoven tasks here: translating identifiers and documenting code. Ideally both would go hand-in-hand. So much code, so little time...
Parsley, sage, rosemary, and maggikraut.

whoami

So I understand that my approach is still under consideration. That allows me to continue.

eipi

The translation patches have been updated against r5788. I made some small updates to ./bauer and ./besch.

As to the file header comments: What about something like this:


/**
* This file is under <this particular license>.
* See "license.txt".
*
* @file <filename> <One-sentence description>
* @author <Author>
* @date <Last edit date>
*/


Suggestions are welcome (also for the patches :))

Dwachs

Quote from: eipi on June 28, 2012, 11:06:18 AM
The translation patches have been updated against r5788. I made some small updates to ./bauer and ./besch.
Where is the patch file ???

Quote from: eipi on June 28, 2012, 11:06:18 AM
As to the file header comments: What about something like this:
Looks good. The source code is under artistic license. I would leave out @date and @author comments as these will be outdated very soon.

Parsley, sage, rosemary, and maggikraut.

eipi

The above links I posted still work, I'll post them again:

https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation_bauer.patch
(for the changed files in ./bauer only, because I'm still working on the other parts)

https://dl.dropbox.com/u/53679800/Simutrans/patches/SimuTranslation.patch
(the whole patch)