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++ » U++ Developers corner » Documentation and Topic++
Re: Documentation and Topic++ [message #13045 is a reply to message #13042] Thu, 06 December 2007 21:49 Go to previous messageGo to next message
Novo is currently offline  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 Go to previous messageGo to next message
Mindtraveller is currently offline  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 #13121 is a reply to message #13116] Thu, 13 December 2007 18:27 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Mindtraveller wrote on Wed, 12 December 2007 17:20


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.


I do understand "open it not in view mode (not edit)" part..

Mirek
Re: Documentation and Topic++ [message #13124 is a reply to message #12713] Fri, 14 December 2007 05:57 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

I misspelled. That should read as: "in view mode, not in edit".
Re: Documentation and Topic++ [message #13128 is a reply to message #13124] Fri, 14 December 2007 17:17 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Mindtraveller wrote on Thu, 13 December 2007 23:57

I misspelled. That should read as: "in view mode, not in edit".


In that case, it should not matter. As soon as you place it to src or srcdoc group, you should be able to see it in view mode. (somewhere in the tree...)

Mirek
Re: Documentation and Topic++ [message #15265 is a reply to message #13128] Mon, 14 April 2008 11:27 Go to previous messageGo to next message
mrjt is currently offline  mrjt
Messages: 705
Registered: March 2007
Location: London
Contributor
Is there currently any way to have TheIDE create a structured src documentation file for a class/package. i.e. a file with all the methods and parameters listed in Upp style with only the comments missing?

[Updated on: Mon, 14 April 2008 12:05]

Report message to a moderator

Re: Documentation and Topic++ [message #15266 is a reply to message #15265] Mon, 14 April 2008 14:26 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mrjt wrote on Mon, 14 April 2008 05:27

Is there currently any way to have TheIDE create a structured src documentation file for a class/package. i.e. a file with all the methods and parameters listed in Upp style with only the comments missing?


Yes , if I understand well the question...:

http://www.ultimatepp.org/app$ide$Topic$en-us.html

Mirek
Re: Documentation and Topic++ [message #15267 is a reply to message #15266] Mon, 14 April 2008 14:40 Go to previous messageGo to next message
mrjt is currently offline  mrjt
Messages: 705
Registered: March 2007
Location: London
Contributor
Perfect! Thanks.
Re: Documentation and Topic++ [message #16360 is a reply to message #15267] Tue, 10 June 2008 17:13 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Since we are getting pretty close to 2008 release, do you think it's time to reopen the discussion about a new Topic++ and documentation? Do you think this is going to be a focus area before the release of the first 8xx dev?
Re: Documentation and Topic++ [message #16361 is a reply to message #16360] Tue, 10 June 2008 18:35 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Well, yes, for me, assist++ and topic++ are now in focus Smile

Mirek
Re: Documentation and Topic++ [message #16391 is a reply to message #16361] Thu, 12 June 2008 13:02 Go to previous messageGo to next message
cbpporter is currently offline  cbpporter
Messages: 1401
Registered: September 2007
Ultimate Contributor
Well, I propose something like this:

index.php?t=getfile&id=1235&private=0


What can not be seen from this mock-up, is that all parts except the class description, the see also section and the logical grouping of methods should be auto generated. Also future auto generatations would not destroy available documentation.
  • Attachment: untitled2.PNG
    (Size: 22.54KB, Downloaded 805 times)
Re: Documentation and Topic++ [message #16395 is a reply to message #16391] Thu, 12 June 2008 17:36 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
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 Smile 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
Re: Documentation and Topic++ [message #16401 is a reply to message #16395] Thu, 12 June 2008 20:25 Go to previous messageGo to next message
zsolt is currently offline  zsolt
Messages: 693
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 Smile 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 Go to previous messageGo to next message
cbpporter is currently offline  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 #16403 is a reply to message #16402] Thu, 12 June 2008 23:35 Go to previous messageGo to next message
mrjt is currently offline  mrjt
Messages: 705
Registered: March 2007
Location: London
Contributor
I'll contribute some documenting once you guys have figured out how it's going to work Smile

My only suggestion is that instead of just saying 'submit some documentation', what would make contributing easier is a list of all (or many) of the things (classes, features, genrenal areas whatever) that need docs. That way people could look at the list and say to themselves 'I know about that, I'll write some docs', rather than not knowing where to start. IMHO obviously, but it's one of the things that has stopped me so far.
Re: Documentation and Topic++ [message #16407 is a reply to message #16403] Fri, 13 June 2008 09:36 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mrjt wrote on Thu, 12 June 2008 17:35

I'll contribute some documenting once you guys have figured out how it's going to work Smile

My only suggestion is that instead of just saying 'submit some documentation', what would make contributing easier is a list of all (or many) of the things (classes, features, genrenal areas whatever) that need docs.



Actually, the main point of my above idea is that you will see what methods are not documented while editing the code.. (with different icon in the left bar).

Mirek
Re: Documentation and Topic++ [message #16408 is a reply to message #16402] Fri, 13 June 2008 09:45 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
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 Smile

[Updated on: Fri, 13 June 2008 09:47]

Report message to a moderator

Re: Documentation and Topic++ [message #16437 is a reply to message #16408] Sun, 15 June 2008 14:59 Go to previous messageGo to next message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

I would like to see more manual-oriented docs. It seems much more effective than simple listing of classes (which is very useful in a number of cases). I like it because knowing all the methods doesn`t guarantee knowing how to use them effectively.
This is especially actual for U++ which introduces innovative and uncommon approach in many aspects of C++ programming.
These two doc types - reference and manual, should be tightly connected and crosss-referenced.
So, agreeing with words above about making big list of all planned classes tipics, I`d add that we should plan the general structure of manual-type docs. That is the thing I mensioned some time ago and now I put it into discussion again.
Re: Documentation and Topic++ [message #16440 is a reply to message #16437] Sun, 15 June 2008 19:03 Go to previous messageGo to next message
mdelfede is currently offline  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
Re: Documentation and Topic++ [message #16443 is a reply to message #16440] Sun, 15 June 2008 21:26 Go to previous messageGo to previous message
Mindtraveller is currently offline  Mindtraveller
Messages: 917
Registered: August 2007
Location: Russia, Moscow rgn.
Experienced Contributor

I think it is time to create topic where we discuss manual docs structure.
Classes and functions reference should be another one parallel topic.
Previous Topic: Task: How to read GTK/Gnome settings
Next Topic: U++ infrastructure server...
Goto Forum:
  


Current Time: Fri Mar 29 14:10:04 CET 2024

Total time taken to generate the page: 0.03608 seconds