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 » T++ working
Re: T++ working [message #19061 is a reply to message #19057] Sat, 08 November 2008 10:36 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
captainc wrote on Sat, 08 November 2008 00:41

Great stuff. You rock. Twisted Evil

Thanks! I intend, with a little help from you all of course, to get everything that is worth documented from Core documented. And Chameleon too. The rest like CtrlLib, PDF, etc. I'll have to leave to others Razz.

I added documentation for Rect_. It does not contain all the methods, but I'll ad them in the next session. Rect is a little bloated.

Also a question: what is with all the tpp. files. They seem to be generated on the fly. And what about all.i. I also get the impression that those files should not be up on SVN.

And a suggestion: sure, the new system is great,but if you are not using the help browser, you are stuck with having to browse sources to get the documentation for something. It would be great to add a small description frame in the bottom of the auto-complete window. When pressing . and using the cursor to highlight a method, the description should pop up bellow the class list and the method list, with exactly the same content as if I were to hover my mouse over the respective little icon.
Re: T++ working [message #19063 is a reply to message #19049] Sat, 08 November 2008 14:24 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Fri, 07 November 2008 09:54


I'm using the new reference type without the leading "::". I hope that this will be final.



Seriously, maybe it is not. In fact, the correct would be "Upp::" leading.

Anyway, the problem here now is that current parser does not "do" namespaces and there is no simply way how to achieve that. Therefore I have decided to simply ignore them; but in that case it is much more correct to just leave initial "::" out (as that would mean "global namespace"; moreover such coderef is 2 bytes shorter. That is why the change.

If we ever figure out how to deal with namespaces, be sure I will provide a transition path...

Quote:


Regarding the friend functions, I see the problem. More thought is needed. They do seam to belong to both scopes logically.


After more thinking, I have decided that perhaps we should deal with them as with methods... Especially inline friends, because they are in fact affected by actual template parameters.

Mirek
Re: T++ working [message #19064 is a reply to message #19053] Sat, 08 November 2008 14:27 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Fri, 07 November 2008 15:17

I finished MathUtil, except for about six function which I don't know what they do exactly, so I've left them empty rather than write an approximate description.



I will alert the author Smile

Quote:


I also extracted the constructors and destructor of Vector to it's own section, like in other docs. It is distracting to read a function doc, then a couple of constructors, then a destructor, then again some functions, then another constructor. Having them in the same place is better IMO.



I do not know, but perhaps it is really a little bit better.

BTW, it seems like export to HTML of these tables is a little bit wanting. Something to check...

Quote:


I can also do a check-up round on all the other docs from Core if you don't mind. I saw that most have their references fixed.


Excellent. Please, update from svn before each run, I am fixing random topics as well.

Mirek
Re: T++ working [message #19072 is a reply to message #19064] Sun, 09 November 2008 10:48 Go to previous messageGo to next message
mdelfede is currently offline  mdelfede
Messages: 1307
Registered: September 2007
Ultimate Contributor
Wow, I like the style of added/completed docs.... great job ! Smile

Max
Re: T++ working [message #19142 is a reply to message #19072] Fri, 14 November 2008 21:34 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
I updated another bunch of documentation files. Nothing very interesting Smile.

The only problem was String. String is extremely complicated and this makes it hard to document. If I maintain the current style with String and WString documented together, it makes the document more concise, but it leaves a lot of code without document references, making the little icons useless. String being so complicated should get all the help that it can get.

On the other hand, if I document them separately, the documentation becomes a little more redundant, but more items are documented.

I tried something experimental: I documented String as if were a normal class without that complex templated inheritance. Wstring will be documented with the same approach. And AString will be also documented as an interface that bridges between the two types. If a method appears in all 3 classes, like with Cat, the same documentation will be copied to String (String0 that is, but I left String0 undocumented as I considerate a private implementation detail), WString (WString0) and AString. This way if someone reads String code or documentation, all the info will be available. If someone browses over AString code, then again valid documentation will be available.

You can check it out in SVN. I left the old doc intact, but prepended it with a String doc. Let me know what you think about this approach. Another approach would be to allow a documentation to be linked to multiple definitions, but I would prefer to not further complicate A++.

Quote:

Also a question: what is with all the .tppi. files. They seem to be generated on the fly. And what about all.i. I also get the impression that those files should not be up on SVN.


I would still like to know the answer.
Re: T++ working [message #19150 is a reply to message #19061] Sat, 15 November 2008 14:48 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Sat, 08 November 2008 04:36


Also a question: what is with all the tpp. files. They seem to be generated on the fly. And what about all.i. I also get the impression that those files should not be up on SVN.



tppi files are "included" files into C++. They are only relevant if you are using T++ for application docs, e.g. help (appdoc group is reserved for this purpose).

You need to explicitly activate generation of tppi by making the group "includeable".

Note: 2008.1 used identical format in all cases. Anyway, that did not played well with conflicts in svn, as the format was basically compressed -> that is why I have made the change. (The idea is, of course, that you can safely ignore the conflict in tppi, just serve the tpp problem).

As for those files being required in svn, hard to say. You cannot compile without them and you need theide to generate them and they do NOT get generated before compilation even in theide.

IMO, ignoring them for svn would cause more troubles than having them there.

Mirek
Re: T++ working [message #19151 is a reply to message #19142] Sat, 15 November 2008 14:50 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Fri, 14 November 2008 15:34

I updated another bunch of documentation files. Nothing very interesting Smile.

The only problem was String. String is extremely complicated and this makes it hard to document. If I maintain the current style with String and WString documented together, it makes the document more concise, but it leaves a lot of code without document references, making the little icons useless. String being so complicated should get all the help that it can get.



The very same issue is Callback...

Actually, this is the very last issue I feel needs solving.

I think that we definitely need to be able to work with more than one coderef in code (Size_{ T x, y; } situation) and also more than one coderef in T++ (means, the line would be shared).

Mirek
Re: T++ working [message #19196 is a reply to message #19151] Wed, 19 November 2008 13:17 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Updated documentation for String, StringBuffer and Stream.

Maybe it's time to make the documentation icons which appear in the code reference chooser dialog appear for the variants without the ::.
Re: T++ working [message #19199 is a reply to message #19196] Wed, 19 November 2008 15:29 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Any, One and SerializationUtils documentation update.
Re: T++ working [message #19202 is a reply to message #19199] Wed, 19 November 2008 22:47 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Thanks, excellent job!

Mirek
Re: T++ working [message #19211 is a reply to message #19202] Thu, 20 November 2008 14:30 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Buffer, Pte, Ptr and BiVector documentation.

I hope Buffer isn't deprecated.

How about Bits, Mitor, Link, etc... Are these types used by anybody?
Re: T++ working [message #19218 is a reply to message #19211] Fri, 21 November 2008 03:10 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
If they are not, I'm guessing its because there are not docs for them.
Re: T++ working [message #19219 is a reply to message #19218] Fri, 21 November 2008 07:34 Go to previous messageGo to next message
tojocky is currently offline  tojocky
Messages: 607
Registered: April 2008
Location: UK
Contributor

I'm interesting in link. dynamic and static link!
Re: T++ working [message #19225 is a reply to message #19219] Fri, 21 November 2008 15:41 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
CParser doc done too.

Only one this time, but I did have a little more work with this one.

First of all, even though there was a little header announcing with big brown letters the beginning of a section, I found it quite difficult to distinguish at a glance between sections. Very poor contrast and a poor visual cue. So I tried using a more visible header, and I'm more satisfied with this one (maybe better color could be used). What do you think?

Second: for this documentation page I heavily used hyperlinks to connect different parts of documentation. I'll wait until site gets updated to see if HTML can handle these. By the way, back is not that smart.
Re: T++ working [message #20323 is a reply to message #19225] Tue, 10 March 2009 18:59 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
During the last few days I've been updating documentation pages. Soon entire available Core docs will be ready.

But the way those tables have a spacing on the left & right is really annoying and makes documentation ugly.

I attached a simple fix to remove the spacing. Spacing can still be provided by editing table options, but I think some CSS parameters are needed to handle that one correctly.

Also, the generated HTML is really cute, kind of reminds me 1998, except that it has CSS. Could I change the generated HTML so it is more like the W3C recommendation for HTML + XHTML interop?
Re: T++ working [message #20325 is a reply to message #20323] Tue, 10 March 2009 22:40 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
cbpporter wrote on Tue, 10 March 2009 13:59

During the last few days I've been updating documentation pages. Soon entire available Core docs will be ready.

But the way those tables have a spacing on the left & right is really annoying and makes documentation ugly.

I attached a simple fix to remove the spacing. Spacing can still be provided by editing table options, but I think some CSS parameters are needed to handle that one correctly.



Patch accepted, thank you. (I hope we will see results tomorrow Smile

Quote:


Also, the generated HTML is really cute, kind of reminds me 1998, except that it has CSS. Could I change the generated HTML so it is more like the W3C recommendation for HTML + XHTML interop?


What do you exactly mean by better HTML + XHTML interop? I am OK with improvements, the only thing I would like to care about is the size of resulting .html (in fact, I am sort of using that CSS as compression tool...).

Mirek
Re: T++ working [message #20326 is a reply to message #20325] Wed, 11 March 2009 12:01 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Results are much better. Still a little margin visible, but I'll fix that together with my proposal for HTML generation.

As for the generated HTML, I think that any web developer who writes such HTML in 2009 should immediately buy a book on this subject and not leave the house until he can write pages that actually have a chance of passing any validation Smile. And since XHTML is pretty much a subset of HTML, and XHTML code is valid HTML code, all code should be XHTML compatible, albeit sans the XML headers.

PS: I updated Pusher and all derived control documentation (except for OptionButton). I can't commit just yet because my new security measures keep me cut of from SVN. I'll commit from different computer latter. Just letting everybody know, so that we are not working on the same pages.

Also, I started going over old unresolved issues of mine. I'll start giving them arbitrary numbers to keep track.

Issue #001 is documentation. Am working on it.

Issue #002. The code reference window used to show little icons for documented items. With new changes, this feature was lost, but it still works for public functions, but not class members. So either make it work for everything, or remove it completely.

[Updated on: Wed, 11 March 2009 12:03]

Report message to a moderator

Re: T++ working [message #20337 is a reply to message #20326] Thu, 12 March 2009 11:56 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
I tried running some validations on the generated HTML. I navigated to the CParser documentation, and ran validation on it, together with U++ site content. I got 76 errors. After I ran validation on content only, without U++ site, and got 0 errors. Pretty good, this means generation is OK.

Then I switched document type to XHTML and got 2579 error with U++ site, and 2157 without site. Seeing that these two formats are almost identical, such a huge number of error is not a good think.

I uploaded a version of EncodeHtml that keep 0 errors for HTML, and reduces errors to 150 for XHTML. There is still lots to be improved, but I wouldn't like to submit large changes all at once.

HTML size is a little bigger, but it's negligible.

Also fixes the last padding issues I could find.
Re: T++ working [message #20351 is a reply to message #20337] Fri, 13 March 2009 09:35 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Applied.

Should not be HtmlDot "treated" with \" as well? (I guess, could be done in HtmlDot).

Mirek
Re: T++ working [message #20362 is a reply to message #20351] Sat, 14 March 2009 09:55 Go to previous message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Great! Everything looks good. Extra padding is gone. I ran validation tests and there are still some errors, but nothing to prevent proper rendering (I hope Smile ). While fixing validation is something to thing about, I won't waste too much time with it right now.

But there are still some small improvements to the generation which I'll post. For some things you are using and verbose way and I think I can make it shorter and clear. Another thing to think about is CSS inheritance, which should make things yet again clear.

Quote:

Issue #002. The code reference window used to show little icons for documented items. With new changes, this feature was lost, but it still works for public functions, but not class members. So either make it work for everything, or remove it completely.

The problem is that you are not setting the scope field properly. Adding:
m.scope = scope;

to ide\Browser\CodeBrowser.cpp around line 187 seems to do the trick. Maybe you can find better fix.
Previous Topic: Notes on using T++ (comment on singals)
Next Topic: List of patterns to be explained in article
Goto Forum:
  


Current Time: Thu Mar 28 18:22:43 CET 2024

Total time taken to generate the page: 0.02059 seconds