U++ forum: Welcome to the forum

Re: Documentation how-to... [message #17976 is a reply to message #17975]

Fri, 05 September 2008 13:32

cbpporter
Messages: 1401
Registered: September 2007

Ultimate Contributor

luzr wrote on Fri, 05 September 2008 11:06

Same here

Looks like I have to add horizontal rulers to the RichText ? Smile

I guess it is easier than upgrading the tabling possibilities of RichEdit.

Quote:

Anyway, from practical standpoint, I have to repeat that for the future, we absolutely need semi-fixed structure there, so that we can display according documentation in class browser etc...

I'm not sure that I understand what you mean.

OK, so the documentation process isn't of to a great start, but it is still a start.

I feel that for better results, we need to have a (better) plan. I'm still busy as I announced earlier so I can't really sit down and code (maybe for very small things). But I can sit down and document. So I'll try to produce 3 documentation pages in the next week. I'll write them in open office, without any special formating, and wait for us to decide on the style. When Topic++ is a little bit more stable with the function references, we should start moving the pages to Topic++. It won't be that fun, but will go quite fast.

It would be also great if possible other volunteers that are willing to document something would say so in this thread.

My first targets are: the stuff in Defs.h and Cpu.cpp for one. Not that much work and a little help on this part maybe would clear up some confusion regarding endianess. A question here: wouldn't this be a good time to clean up Defs.h a little. There are some useful macros, but also a lot of macros which could be implemented as inlines, like MAKEWORD.

Another target is Lang. I saw a fair number of question related to how one set's the application language and related. But here I can't shake the feeling that Lang is in need of major clean-up and refactoring.

VectorMap<String, String> GetLanguage(int lang);//rename...

Rename indeed. Other stuff is commented with deprecated.

Also, judging by the way functions and LanguageInfo is implemented, I really don't see the sense of a function like:

String GetLangName(int language)
{
	return GetLanguageInfo(language).english_name;
}

It should be IMO:

LanguageInfo(language).GetName();

or at least:

GetLangInfo(language).GetName();

The question is if it is worth documenting such stuff right now, or is better to wait a little and clean up some stuff? As I said, time is a little scarce for me right now, but I could replace that time that I allocated for doc writing with refactoring time. And we could move all the deprecated function in a separate .h and gradually phase them out. Such functions that are deprecated and grouped together will eventually get so out of sync with the rest of the code base, that at a release we'll choose just to drop those files. By then everybody should have had ample time to adapt to the new API.

Report message to a moderator