Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site
Search in forums












SourceForge.net Logo
Home » Developing U++ » Documentation » Documentation how-to...
Re: Documentation how-to... [message #17975 is a reply to message #17974] Fri, 05 September 2008 10:06 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
captainc wrote on Thu, 04 September 2008 19:32

I'm a fan of 03.pdf.



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

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...

Mirek
Re: Documentation how-to... [message #17976 is a reply to message #17975] Fri, 05 September 2008 13:32 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Fri, 05 September 2008 11:06


Same here Smile 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.
Re: Documentation how-to... [message #17977 is a reply to message #17976] Fri, 05 September 2008 14:17 Go to previous messageGo to next message
mirek is currently offline  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 Smile 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.

[quote]

Actually, the .pdf you have posted all qualify... Smile

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 Wink

Mirek
Re: Documentation how-to... [message #17978 is a reply to message #17977] Fri, 05 September 2008 14:20 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Quote:

LanguageInfo is not

Is not what?
Re: Documentation how-to... [message #17979 is a reply to message #17607] Fri, 05 September 2008 15:10 Go to previous messageGo to next message
mr_ped is currently offline  mr_ped
Messages: 825
Registered: November 2005
Location: Czech Republic - Praha
Experienced Contributor
03.pdf looks best to me, although a mix 01 vs 03 would be maybe interesting for me too... 02 has too many graphical things to distract from the content itself.
Re: Documentation how-to... [message #17980 is a reply to message #17979] Fri, 05 September 2008 15:47 Go to previous messageGo to next message
captainc is currently offline  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 #17981 is a reply to message #17980] Fri, 05 September 2008 16:52 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
I must confess that I find Dox style quite fetching and extremely easy to read. It is quite similar to style number 3, which seems to be the winner here, but the colors are more fitting.

Try and browse a little some pages <a href="http://libagp.narechk.net/manual/api/html/[main]-index.html">Here</a>. I also attached a quick mock-up of the style.

The real challenge is going to be to get topic to do that.
  • Attachment: 04.pdf
    (Size: 43.54KB, Downloaded 522 times)
Re: Documentation how-to... [message #17982 is a reply to message #17981] Fri, 05 September 2008 17:15 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
cbpporter, Can you upload your Upp styles?

Edit: Oh wait, these are OpenOffice right?

[Updated on: Fri, 05 September 2008 17:17]

Report message to a moderator

Re: Documentation how-to... [message #17983 is a reply to message #17982] Fri, 05 September 2008 18:11 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
captainc wrote on Fri, 05 September 2008 18:15

cbpporter, Can you upload your Upp styles?

Edit: Oh wait, these are OpenOffice right?

I'll try to reproduce the style in Topic.
Re: Documentation how-to... [message #17989 is a reply to message #17983] Fri, 05 September 2008 20:29 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
This was the best I could come up with.

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. Just a lot harder than it should be.

Also, I'm starting to have doubts in Qtf as a good format for large texts.

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. Also, don't insert two spaces where one needs to insert text, because it is very annoying to delete them. And set proper style for parameters, together with the tab character (and again, no two spaces).
Re: Documentation how-to... [message #17990 is a reply to message #17989] Fri, 05 September 2008 20:35 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Fri, 05 September 2008 14:29


A full template corresponding to out chosen style is generated



Should not there be just one style?

Mirek
Re: Documentation how-to... [message #17991 is a reply to message #17990] Fri, 05 September 2008 20:37 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Sure.
Re: Documentation how-to... [message #17992 is a reply to message #17989] Fri, 05 September 2008 20:53 Go to previous messageGo to next message
mirek is currently offline  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.



Smile

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 Go to previous messageGo to next message
cbpporter is currently offline  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.
Re: Documentation how-to... [message #17994 is a reply to message #17991] Fri, 05 September 2008 20:59 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
I added some socket documentation to the Web package in srcdoc. I may have to clean it up though to make the distinction between other parts of the web package (http, smtp, auth, etc.).
Re: Documentation how-to... [message #18015 is a reply to message #17994] Sat, 06 September 2008 21:05 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Documentation for Size_. Friend methods an OS dependent stuff not covered.
Re: Documentation how-to... [message #18017 is a reply to message #18015] Sat, 06 September 2008 21:17 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Sat, 06 September 2008 15:05

Documentation for Size_. Friend methods an OS dependent stuff not covered.


Ehm, I guess you are missing svn access to commit docs...

Something to fix.

Mirek
Re: Documentation how-to... [message #18022 is a reply to message #18015] Sun, 07 September 2008 08:59 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Sat, 06 September 2008 15:05

Documentation for Size_. Friend methods an OS dependent stuff not covered.


Well, it seems like we are picking some steam now Smile

Style discussion:

Size_(const Point_<T>& pt)
Creates a Size_ object and initializes it with a Point object.
pt.......the point object

Well, maybe the separate list of parameters is not really needed, especially if parameter names are there with different color. You use the same style in other methods:

Size_(const Point_<T>& pt)
Creates a Size_ object and initializes it with a Point object *pt*.

(besides, I would not call pt the object, but "Point value" or just "Point" Smile

Mirek
Re: Documentation how-to... [message #18023 is a reply to message #18022] Sun, 07 September 2008 09:00 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
PS.: Interesting way how to achieve horizontal ruler Smile
Re: Documentation how-to... [message #18024 is a reply to message #18022] Sun, 07 September 2008 09:20 Go to previous messageGo to previous message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
luzr wrote on Sun, 07 September 2008 09:59


Well, it seems like we are picking some steam now Smile


Yes! I'll document the pages that I promised now, and I'll do more when Topic++ becomes better. captainc is doing great with Sql and Web. Little by little we'll get there. Maybe you could do MT one day? I'm not touching that one Razz.

Quote:


Well, maybe the separate list of parameters is not really needed, especially if parameter names are there with different color. You use the same style in other methods:


It is harder to document such a straight forward class than a complicated one. It's harder to expree in words the obvious. I was trying to decide between being consistent and concise. But I guess it's okay to skip parameter list with such simple cases, and only use them when really needed.

Quote:


PS.: Interesting way how to achieve horizontal ruler


Yeah, it is a good stand-in, but will replace with proper HR when available. And I have no idea how it behaves when exported as html.
Previous Topic: The very first taste of T++ icons in the left bar..
Next Topic: Notes on using T++ (comment on singals)
Goto Forum:
  


Current Time: Fri Mar 29 00:15:54 CET 2024

Total time taken to generate the page: 0.01792 seconds