|
|
Home » Developing U++ » U++ Developers corner » Documentation and Topic++
Re: Documentation and Topic++ [message #13045 is a reply to message #13042] |
Thu, 06 December 2007 21:49 |
Novo
Messages: 1358 Registered: December 2006
|
Ultimate Contributor |
|
|
luzr wrote on Thu, 06 December 2007 15:10 |
Novo wrote on Thu, 06 December 2007 14:05 |
Mindtraveller wrote on Wed, 05 December 2007 12:19 |
Is it OK, any corrections?
|
Documentation in source code would be very handy.
One line per method (at least).
|
Planned de facto equivalent of what you want.
Mirek
|
Do you mean "indexed source-autogenerated articles accessed via Topic++"?
No real documentation in source code, documentation is dynamically generated by Topic++?
Regards,
Novo
|
|
|
Re: Documentation and Topic++ [message #13116 is a reply to message #12713] |
Wed, 12 December 2007 23:20 |
Mindtraveller
Messages: 917 Registered: August 2007 Location: Russia, Moscow rgn.
|
Experienced Contributor |
|
|
Writing "manual" help pages in current TheIDE version, what package should I add them to? I`d like these articles in the future to be "standalone" help articles accessible through "Manual" tab of new version of help system. Of course, after approval and changing of U++ authors.
For now, I`ve made different .tpp file, but didn`t find the way to open it not in view mode (not edit) and don`t know if it will be possible to move these articles to "manual" help mode.
[Updated on: Thu, 13 December 2007 02:19] Report message to a moderator
|
|
|
|
|
|
|
|
|
|
|
|
|
Re: Documentation and Topic++ [message #16401 is a reply to message #16395] |
Thu, 12 June 2008 20:25 |
zsolt
Messages: 698 Registered: December 2005 Location: Budapest, Hungary
|
Contributor |
|
|
luzr wrote on Thu, 12 June 2008 17:36 | Well, this sounds good - for class browser.
Anyway, the goal I am currently pursuing is to show topic++ related to regular code editing. The idea is that in the left bar area, where breakpoints are, all lines with items with existing or even *potential* Topic++ entry will have an icon. Moving the mouse over that will display tooltip (rather big one with help, clicking it will move you to the entry in Topic++ - if does not exist, it will create one.
Another issue is related to the need of community provided docs, so that we will finally start moving here... I guess it it will be very useful to be able to split source tree and topic tree (as option), so that all U++ docs can be kept and maintained separately (I think tha topic++ repository can have more relaxed access).
Mirek
|
I think, this is a very very good idea.
|
|
|
Re: Documentation and Topic++ [message #16402 is a reply to message #16395] |
Thu, 12 June 2008 22:46 |
cbpporter
Messages: 1401 Registered: September 2007
|
Ultimate Contributor |
|
|
luzr wrote on Thu, 12 June 2008 18:36 | Well, this sounds good - for class browser.
|
Well this was more of an idea for the main documentation presentation, a replacement for the current structure of the Topic++ articles.
This is something of a solution to what I perceive as the tree main disadvantages of the current system:
1. It is far from complete (as in coverage of the API) and quite selective. Some parts are explained in great detail, while others are barely mentioned. It is also not uniform, neither as formating or style.
2. It is not that cross referenced. For example, when I'm browsing the SetStyle function for a class, I would like to have the definition of that style and a srcdoc style article related to what is Chameleon and how to use it, at my fingertips, both only a click way. When I'm browsing the documentation for String, I want to have a list will all the stand alone functions that work on string, preferably ordered by category. For example, I had often had a self written Join function, before I found out that there was one already implemented.
3. The current documentation for classes are hard to read because the text follows every method. This is daunting for someone new to the framework, who is trying to find something and has at least to skim through all that text. And is annoying for someone familiar with the framework, because these persons really don't need to have text displayed for the methods they already know.
But my idea and your approach are anyway not auto-exclusive. Both can use the same information, only the presentation is different. And the analogy with a browser is logical, since I was thinking of extending a browser window with an editor to enter a description for each item and a category for it. This meta information would them be used for the auto generated pages and could also allow atomic commits to that repository you talked about. When someone is using the normal browser, an icon could show that it has no documentation attached, and somebody might be willing to fill it out, submit it and not have to worry about formating or ruining something in a larger document.
Anyway, my ideas are heavily influenced by three really good help systems (IMHO): Delphi help files, PHP documentation and JavaDoc.
|
|
|
|
|
Re: Documentation and Topic++ [message #16408 is a reply to message #16402] |
Fri, 13 June 2008 09:45 |
|
mirek
Messages: 13980 Registered: November 2005
|
Ultimate Member |
|
|
cbpporter wrote on Thu, 12 June 2008 16:46 |
luzr wrote on Thu, 12 June 2008 18:36 | Well, this sounds good - for class browser.
|
Well this was more of an idea for the main documentation presentation, a replacement for the current structure of the Topic++ articles.
This is something of a solution to what I perceive as the tree main disadvantages of the current system:
1. It is far from complete (as in coverage of the API) and quite selective. Some parts are explained in great detail, while others are barely mentioned. It is also not uniform, neither as formating or style.
2. It is not that cross referenced. For example, when I'm browsing the SetStyle function for a class, I would like to have the definition of that style and a srcdoc style article related to what is Chameleon and how to use it, at my fingertips, both only a click way. When I'm browsing the documentation for String, I want to have a list will all the stand alone functions that work on string, preferably ordered by category. For example, I had often had a self written Join function, before I found out that there was one already implemented.
3. The current documentation for classes are hard to read because the text follows every method. This is daunting for someone new to the framework, who is trying to find something and has at least to skim through all that text. And is annoying for someone familiar with the framework, because these persons really don't need to have text displayed for the methods they already know.
But my idea and your approach are anyway not auto-exclusive. Both can use the same information, only the presentation is different. And the analogy with a browser is logical, since I was thinking of extending a browser window with an editor to enter a description for each item and a category for it. This meta information would them be used for the auto generated pages and could also allow atomic commits to that repository you talked about. When someone is using the normal browser, an icon could show that it has no documentation attached, and somebody might be willing to fill it out, submit it and not have to worry about formating or ruining something in a larger document.
Anyway, my ideas are heavily influenced by three really good help systems (IMHO): Delphi help files, PHP documentation and JavaDoc.
|
Well, I have to say that I have had "internal fight" between the two concepts for years - I mean, more database like concept of documentation as you suggest, where each method has its own entry, and document like approach like we have now.
In fact, a couple of years before, the first Topic++ iteration worked like database.
In the end, I prefer current model because of several tiny advantages (if they are advantages):
- you have little bit more flexible ways to organize docs. E.g. quite often it is nice to document a group of methods with single description.
- you have all formating capabilities of RichEdit, so you can put in pictures etc (well, this might be possible with some DB schemes as well I guess)
- and I think you are not really loosing the possiblity to present documentation in class browser JUST LIKE YOU SUGGEST - the topics++ are marked with code labels, so in fact existing topics can act as database too.
Mirek
P.S.: 2. - that is only a matter of putting these links into the text
[Updated on: Fri, 13 June 2008 09:47] Report message to a moderator
|
|
|
|
Re: Documentation and Topic++ [message #16440 is a reply to message #16437] |
Sun, 15 June 2008 19:03 |
mdelfede
Messages: 1307 Registered: September 2007
|
Ultimate Contributor |
|
|
I agree... IMHO the actual document structure isn't enough.
I'd prefere too a different approach, borland's user guides were very effective and comfortable to read... I think that could be a good example. Good old Microsoft guides in chm format were not bad at all too.
Maybe a good stuff would be to have a good underlying doc structure (maybe xml ?) ,separate viewer/browser AND separated doc editor.
We could even have more viewers, to accomodate user's preferences.
But, in my opinion, documents should be cathegorized, indexed and cross-referenced. Looking to a function/class should provide some "see-also" stuff, some examples, link to one or more main topics and so on.
And we should have cathegorized indexes.
Another good point would be to separate (as it was proposed sometimes) documentation from code, and give a more relaxed access to main repository's docs, allowing users to contribute more effectively.
We could even start a new sf project (with its svn repository) to hold just documentation for upp....
Max
|
|
|
|
Goto Forum:
Current Time: Thu May 16 18:19:37 CEST 2024
Total time taken to generate the page: 0.03263 seconds
|
|
|