|
|
Home » Developing U++ » Documentation » Documentation how-to...
|
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 ?
|
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.
|
|
|
Re: Documentation how-to... [message #17977 is a reply to message #17976] |
Fri, 05 September 2008 14:17 |
|
mirek
Messages: 13975 Registered: November 2005
|
Ultimate Member |
|
|
[quote title=cbpporter wrote on Fri, 05 September 2008 07:32]luzr wrote on Fri, 05 September 2008 11:06 |
Same here Looks like I have to add horizontal rulers to the RichText ?
|
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.
[quote]
Actually, the .pdf you have posted all qualify...
The point is: The method documentation shall start with paragraph of its declaration, which should have "label" to connect it to the code. Then should be a paragraph with description of method and list of parameters.
Quote: |
I'll write them in open office, without any special formating, and wait for us to decide on the style.
|
It would be a lot of work to put code labels back, I am afraid.
Anyway, I hope to fix some problems during weekend. Next week I plan a bigger assault on the problem.
.
Quote: |
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.
|
Yes! Alternatively, I will post you parts that are "final".
Quote: |
Also, judging by the way functions and LanguageInfo is
|
LanguageInfo is not
Mirek
|
|
|
|
|
Re: Documentation how-to... [message #17980 is a reply to message #17979] |
Fri, 05 September 2008 15:47 |
captainc
Messages: 278 Registered: December 2006 Location: New Jersey, USA
|
Experienced Member |
|
|
Quote: | A way to change stuff like CSS is used for web pages would simplify thing a lot. Maybe some tables with interchangeable styles.
|
I'm just throwing ideas out, but you got me thinking about this now.
If code documentation is exported as XML, all we would need to do is use a stylesheet to either display the information locally or on the web. We could also leave it up to others who know css well to design different interfaces. Also, tools like doxygen output in XML. We may be able to leverage that fact, just like a program called Dox has (http://dox.narechk.net/index_en.html) or Natural Docs (http://www.naturaldocs.org/). Either that, or give T++ functionality to be a minimal WYSIWYG html editor? We could look at Amaya's code or even the better javascript based WYSIWYG editors.
Oh yeah, and I've used this successfully before too: http://www.doxys.dk/doxys_homepage/index.html
Anyway, just ideas that come to mind...
[Updated on: Fri, 05 September 2008 15:56] Report message to a moderator
|
|
|
|
|
|
|
|
|
Re: Documentation how-to... [message #17992 is a reply to message #17989] |
Fri, 05 September 2008 20:53 |
|
mirek
Messages: 13975 Registered: November 2005
|
Ultimate Member |
|
|
cbpporter wrote on Fri, 05 September 2008 14:29 |
I was very careful not to do something to upset Topic++, and the conclusion is that it can be used (with care) even now to create the docs.
|
Quote: |
Anyway, it would be great help if we could enhance Topic++ to do the following: user creates a new documentation page, browses to some definitions and inserts them. A full template corresponding to out chosen style is generated and all all there is left to do is to fill in the description texts.
|
If I remember well, that is what it does now (?). Except those two spaces, of course.
Quote: |
Also, don't insert two spaces where one needs to insert text, because it is very annoying to delete them.
|
Ops, two spaces was temporary workaround that just stayed there for too long....
Quote: |
And set proper style for parameters, together with the tab character (and again, no two spaces).
|
Again, what should be different? (except the spaces).
Mirek
|
|
|
Re: Documentation how-to... [message #17993 is a reply to message #17992] |
Fri, 05 September 2008 20:59 |
cbpporter
Messages: 1401 Registered: September 2007
|
Ultimate Contributor |
|
|
luzr wrote on Fri, 05 September 2008 21:53 |
If I remember well, that is what it does now (?). Except those two spaces, of course.
|
Almost. I still need to get in, insert some newlines, change some fonts, etc. I would like to have a perfect template, with no housekeeping, just writing or copy pasting descriptions. Right now I spend more time adjusting formats, even when using the style drop down, which even gets it wrong often.
Quote: |
Again, what should be different? (except the spaces).
|
The formating perfect and the tab preinserted. Right now I have to delete the spaces, press tab, and often have to switch to "default" style and then back to "item" so that my tab is picked up and formated correctly.
|
|
|
|
|
|
|
|
|
Goto Forum:
Current Time: Fri Mar 29 09:16:47 CET 2024
Total time taken to generate the page: 0.01408 seconds
|
|
|