Home » Developing U++ » Documentation » T++ working
|
|
|
|
|
|
|
|
|
|
|
|
| Re: T++ working [message #18928 is a reply to message #18922] |
Sat, 01 November 2008 09:03   |
 |
mirek
Messages: 14291
Registered: November 2005
|
Ultimate Member |
|
|
| cbpporter wrote on Fri, 31 October 2008 15:27 |
First of all what happened to code references? They no longer have a leading "::" and the small little boxes only pick up documentation if it's reference does not have the leading "::". Am I supposed to remove the resolution operator from doc references?
|
Yes, I have removed them. They were both redundant and confusing (because, in fact, we are in Upp namespace now).
| Quote: |
Second: does the Alt-10 function still work? If yes, maybe a button for it should be added.
|
It does, but it is considered as temporary hidden helper to convert old docs.
| Quote: |
Third: is the style that is used when inserting new items final? If yes, there are still some small bugs, like the name of the type being underlined sometimes, but other times not.
|
It should be underlined if the type is user defined -> has its own coderef. In that case, hyperlink is created. (Help browser is able to handle coderef hyperlinks).
I have also noticed that at least one time it did not work right - some issue can be there.
| Quote: |
Also a small suggestion: the hyperlink input should have a small "x" button on the right, which clears the hyperlink.
Another suggestion: make the help browser back-buffered. It is extremely flickery.
And a small bug: clicking on the font size toggle button in the help browser does not refresh the content. I have to click on another topic and click back to get an updated font size.
|
[/quote]
OK
Mirek
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Re: T++ working [message #18995 is a reply to message #18992] |
Mon, 03 November 2008 15:45 |
|
mirek
Messages: 14291
Registered: November 2005
|
Ultimate Member |
|
|
| chickenk wrote on Mon, 03 November 2008 08:14 |
Hi,
just a small remark on the new system:
When at least one entry already exists and you want to add another entry documentation, you are not asked if this is a reference or implementation topic. The already existing entry type is used, and corresponding file opened. In the same manner, you can't add an implementation topic to an entry having a reference topic, and vice-versa.
I know the system is not finished, just wanted to make sure you know about that.
Lionel
|
Yes, I am well aware about the problem. The trouble is that I wanted to make it "quick" in the most common case, therefore the heurestic to adopt previous item topic, as long as scope and access mode is the same.
Any ideas for improved heurestics on whether it should go to topic directly or not?
(Of course, another possibility is simply to remove it 
Mirek
|
|
|
|
|
|
|
|
| Re: T++ working [message #19032 is a reply to message #19000] |
Thu, 06 November 2008 19:07 |
cbpporter
Messages: 1428
Registered: September 2007
|
Ultimate Contributor |
|
|
OK, I updated Size_ docs on SVN.
Here area couple of observations:
1. Finally A++ has shaped up and is comfortable to work with both for creating new docs and updating old. It still isn't "just sit down and write", but nothing to complain about really.
2. I updated the definitions to fit "the style" and things look quite good.
One issue: when inserting public fields like "T cx", the "T" isn't colored green as in all the other cases.
3. The way new A++ works with the small icons you have to watch a little what you write. You can't just put a definition, a description, some filler bla bla and a header like "public methods", because everything is going to be included in the pop-up. Easily fixed though by setting some default paragraphs to "class" style.
4. Friend methods do not have the small icons, so I left that part of the doc un-updated.
5. On the line "T cx, cy", when hovering the mouse over the little icon only the last item, i.e. "cy" is shown. Easiest fix is to not put more than one variable in the same declaration.
So please take a look at it and give your opinion. I say it's as good as it gets and A++ definitely has a future and the style can be considered final.
|
|
|
|
|
|
|
|
|
|
|
|
| Re: T++ working [message #19061 is a reply to message #19057] |
Sat, 08 November 2008 10:36 |
cbpporter
Messages: 1428
Registered: September 2007
|
Ultimate Contributor |
|
|
| captainc wrote on Sat, 08 November 2008 00:41 |
Great stuff. You rock. 
|
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  .
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 #19064 is a reply to message #19053] |
Sat, 08 November 2008 14:27 |
|
mirek
Messages: 14291
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 
| 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 #19142 is a reply to message #19072] |
Fri, 14 November 2008 21:34 |
cbpporter
Messages: 1428
Registered: September 2007
|
Ultimate Contributor |
|
|
I updated another bunch of documentation files. Nothing very interesting .
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 |
|
mirek
Messages: 14291
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 #20326 is a reply to message #20325] |
Wed, 11 March 2009 12:01 |
cbpporter
Messages: 1428
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 . 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 |
cbpporter
Messages: 1428
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.
|
|
|
|
|
|
|
|
Goto Forum:
Current Time: Sat Jun 20 12:11:57 GMT+2 2026
Total time taken to generate the page: 0.01449 seconds
|
U++ framework
Search
Help
Members
Register
Login
Home
