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 » Community » Coffee corner » in code comments - doxygen
in code comments - doxygen [message #6642] Tue, 21 November 2006 12:24 Go to next message
qwerty is currently offline  qwerty
Messages: 130
Registered: May 2006
Experienced Member
just thought :

using some specificaly syntax offered by upp ide or in comment syntax(aka visual studio 2005 xml comments)

...

to generate documentation from your code or from upp under specifical circumstances

maybee in future
Re: in code comments - doxygen [message #6649 is a reply to message #6642] Tue, 21 November 2006 18:58 Go to previous messageGo to next message
fallingdutch is currently offline  fallingdutch
Messages: 258
Registered: July 2006
Experienced Member
i would like that, too

Bas
Re: in code comments - doxygen [message #6652 is a reply to message #6649] Tue, 21 November 2006 21:14 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
My idea is to document in parallel using Topic++ and our C++ parser. Similar to doxygen to a degree, but comments are not in the code. This already works pretty well...

In the (near) future, this should be integrated with new class browser - e.g. Assist++ could show help for methods in selection.

Mirek
Re: in code comments - doxygen [message #7219 is a reply to message #6642] Mon, 18 December 2006 19:23 Go to previous messageGo to next message
Balage is currently offline  Balage
Messages: 17
Registered: December 2006
Promising Member
In-code comments tend to be pretty helpful, also the reference generated from it. doxygen is exceptionally good at this.

Maybe consider using it in Upp base source?

As a side note, Assist++ is the very first code-completion feature I have seen in ALL IDEs so far, that really assists in development, and not hinders (I had to turn these things off in other IDEs)!

Assist++ is a GREAT help for me as a beginner, and I think, that by using doxy style docs, Assist++ could even display the /brief of the given function/class, while moving through the available selections. That would be a mighty fine thing! I haven't seen this anywhere yet!
Re: in code comments - doxygen [message #7220 is a reply to message #7219] Mon, 18 December 2006 19:49 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Balage wrote on Mon, 18 December 2006 13:23


Assist++ is a GREAT help for me as a beginner, and I think, that by using doxy style docs, Assist++ could even display the /brief of the given function/class, while moving through the available selections. That would be a mighty fine thing! I haven't seen this anywhere yet!


Well, that is what I mean by better Assist++ / Topic++ integration.

BTW, first signs of this comming are already there: if you perform a Query (to get results in lower paint), right click on the results also lists Topic++ themes related to the item.

Mirek
Re: in code comments - doxygen [message #7221 is a reply to message #6642] Mon, 18 December 2006 20:09 Go to previous messageGo to next message
Balage is currently offline  Balage
Messages: 17
Registered: December 2006
Promising Member
Another thing, is that lots of other libs are using doxygen style commenting. So showing those comments in Assist would be nice. How about that?
Re: in code comments - doxygen [message #7222 is a reply to message #7221] Mon, 18 December 2006 22:26 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
Interesting idea Smile

Mirek
Re: in code comments - doxygen [message #7951 is a reply to message #6642] Thu, 01 February 2007 18:27 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
I've been using Doxygen for my own projects, and once you work with it since the very start, it does produce at least average documentation. In case you really pay time and attention, there's no problem to get on good level. (In my eyes most of SW documentations out there are either utter bad, bad or average, so suggesting "good" level is something like admiration)
While Topic++ allows for excellent documentation if enough time and attention is used, I sort of dislike splitting the documentation from the actual code itself.

For high level documentation of course there's no real code, and it starts to be cumbersome to hold this one directly in sources (for Doxygen), and trying out really high abstraction docs was too complex for me. (while I believe that exactly the area where Topic++ can shine)

But when we get back down to commenting the code on low level, I think Doxygen is pretty much ultimate tool.
Re: in code comments - doxygen [message #8057 is a reply to message #7951] Mon, 05 February 2007 22:57 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mr_ped wrote on Thu, 01 February 2007 12:27


While Topic++ allows for excellent documentation if enough time and attention is used, I sort of dislike splitting the documentation from the actual code itself.



Well, at least it is in the subdirectory....

Quote:


For high level documentation of course there's no real code, and it starts to be cumbersome to hold this one directly in sources (for Doxygen), and trying out really high abstraction docs was too complex for me. (while I believe that exactly the area where Topic++ can shine)

But when we get back down to commenting the code on low level, I think Doxygen is pretty much ultimate tool.


Yes, Doxygen style is seducing and works well for many cases. At the same time, Topic++ is not where I want it to be yet. I would like to postpone the final judgement until we have new class browser with Topic++ integration.

Mirek
Re: in code comments - doxygen [message #8074 is a reply to message #8057] Tue, 06 February 2007 10:11 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
luzr wrote on Mon, 05 February 2007 22:57

I would like to postpone the final judgement until we have new class browser with Topic++ integration.



IMHO it's not as much about what Topic++ *can* do.

It's simply the docs stored not in code, what is main problem.
So whenever you change code, you must run Topic++ to change the help, which will never (ok, with absolutely disciplined programmers it will work superb, but we live in real world) work as good as doxygen's comments which reside inside of the code itself.
Still any lazy programmer will break even doxygen documentation, but the the some-what lazy programmer (who's too lazy to launch Topic++ but not enough lazy to not change comment) will produce better results with doxygen-like approach.

So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.
Re: in code comments - doxygen [message #8075 is a reply to message #8074] Tue, 06 February 2007 10:27 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
mr_ped wrote on Tue, 06 February 2007 04:11

luzr wrote on Mon, 05 February 2007 22:57

I would like to postpone the final judgement until we have new class browser with Topic++ integration.



IMHO it's not as much about what Topic++ *can* do.

It's simply the docs stored not in code, what is main problem.
So whenever you change code, you must run Topic++ to change the help, which will never (ok, with absolutely disciplined programmers it will work superb, but we live in real world) work as good as doxygen's comments which reside inside of the code itself.
Still any lazy programmer will break even doxygen documentation, but the the some-what lazy programmer (who's too lazy to launch Topic++ but not enough lazy to not change comment) will produce better results with doxygen-like approach.

So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.


Well, these arguments are considered and valid.

On the other side of equation there is comfort of Topic++ editor... I can have advanced WYSIWYG formatting, spell checking, pictures...

Mirek
Re: in code comments - doxygen [message #8076 is a reply to message #6642] Tue, 06 February 2007 11:32 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
A bit off-topic: what about spell check inside IDE?
TortoiseSVN does have it when you are adding comment during commit for example, and I found it quite useful. (not even mentioning Firefox 2.0 right now correcting my mistake with "usefull" Wink )

Of course it would require some level of intelligence to understand C/C++ syntax well.

Having system strong enough for example to find DrawPxiel() (but accept DrawPixel()) would be IMHO considerably handy.

Surely not a high priority. but something to put on the consider-list for future years?
Re: in code comments - doxygen [message #8088 is a reply to message #8075] Tue, 06 February 2007 20:29 Go to previous messageGo to next message
darrs is currently offline  darrs
Messages: 5
Registered: October 2006
Location: New Zealand
Promising Member
Another suggestion.

In the editor you could put a little "Topic++" button in the margin next to global declarations / definitions (I'm assuming Assist++ knows how to recognize these). Clicking that would pop-up a small UWord window to document that function / variable (etc). Hovering over the button could show a pop-up tool-tip with that documentation.

Notes:

a) TheIDE would automatically add a copy of the appropriate function/variable declaration to the start of the documentation.

b) The documentation would be added to the standard Topic++ page for that class / module. Viewing the class via normal Topic++ would show all the combined documentation.

c) Editing the documentation via the margin button would only show the documentation for that declaration / definition. A button in the pop up window would close the pop-up window, start normal Topic++ editor and jump to that declaration in the relevant file.

Cheers,
Darrin.
Re: in code comments - doxygen [message #8091 is a reply to message #8088] Tue, 06 February 2007 23:26 Go to previous messageGo to next message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
darrs wrote on Tue, 06 February 2007 14:29

Another suggestion.

In the editor you could put a little "Topic++" button in the margin next to global declarations / definitions (I'm assuming Assist++ knows how to recognize these). Clicking that would pop-up a small UWord window to document that function / variable (etc). Hovering over the button could show a pop-up tool-tip with that documentation.



Exactly. That is what I mean by "let us finish the idea first" Smile

Mirek
Re: in code comments - doxygen [message #10169 is a reply to message #8091] Sat, 23 June 2007 03:20 Go to previous messageGo to next message
fudadmin is currently offline  fudadmin
Messages: 1321
Registered: November 2005
Location: Kaunas, Lithuania
Ultimate Contributor
Administrator
For some time I have been dreaming:
Developers enter comments directly into the code.
Users ask questions directly in the code.
CodeEditor or Assist moves those comments into topic but still "keeps the track" and displays them the same way as #ifdef markers and ... all this connected to the forums-wiki hybrid Smile
Or this is too much? Smile
Re: in code comments - doxygen [message #10170 is a reply to message #10169] Sat, 23 June 2007 07:12 Go to previous messageGo to next message
waxblood is currently offline  waxblood
Messages: 95
Registered: January 2007
Member
fudadmin wrote on Sat, 23 June 2007 03:20

For some time I have been dreaming:
Developers enter comments directly into the code.
Users ask questions directly in the code.
CodeEditor or Assist moves those comments into topic but still "keeps the track" and displays them the same way as #ifdef markers and ... all this connected to the forums-wiki hybrid Smile
Or this is too much? Smile




When you see software produtcs ads you always notice the word "integration" well exposed in bold characters.

Well, this is integration!


David
Re: in code comments - doxygen [message #17244 is a reply to message #8074] Mon, 04 August 2008 15:49 Go to previous messageGo to next message
captainc is currently offline  captainc
Messages: 278
Registered: December 2006
Location: New Jersey, USA
Experienced Member
mr_ped wrote on Tue, 06 February 2007 04:11


So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.

I know this is an older forum post, but I have come to desire functionality in Topic++ that would automatically bring in doxygen/javadoc style comments from header files along with method/class declarations. Would it be difficult to implement/test out this idea? I find it very easy to update in-code documentation. It is more convenient than external documentation because the code is still fresh in mind and documentation right there. Presenting only a subset of documentation for API purposes through Topic++ would be ideal.
Re: in code comments - doxygen [message #17247 is a reply to message #17244] Mon, 04 August 2008 17:05 Go to previous message
mirek is currently offline  mirek
Messages: 13975
Registered: November 2005
Ultimate Member
captainc wrote on Mon, 04 August 2008 09:49

mr_ped wrote on Tue, 06 February 2007 04:11


So the Topic++ will be always 1 step behind doxygen on the low level documentation, unless you merge the best of both worlds i.e. add features into Topic++ which will analyze the code itself and extract the low level documentation directly from code and comments just like doxygen does.

I know this is an older forum post, but I have come to desire functionality in Topic++ that would automatically bring in doxygen/javadoc style comments from header files along with method/class declarations. Would it be difficult to implement/test out this idea? I find it very easy to update in-code documentation. It is more convenient than external documentation because the code is still fresh in mind and documentation right there. Presenting only a subset of documentation for API purposes through Topic++ would be ideal.



Once we have more solid parser, it should be quite possible.

Mirek
Previous Topic: A Newbie Manual cum Tutorial?
Next Topic: Ultimate++ Website Logo Text
Goto Forum:
  


Current Time: Fri Mar 29 16:43:49 CET 2024

Total time taken to generate the page: 0.01238 seconds