CND69Doxygen

(Difference between revisions)
(→Integration with Code Completion)
 
(56 intermediate revisions not shown)
Line 1: Line 1:
==CND 69 Doxygen==
==CND 69 Doxygen==
-
Doxygen is a tool to convert your C++ comments into publishable HTML.  It works by extracting commentary directly from the source with the help of a special Doxygen syntax.
+
Doxygen commands are embedded commands in sources the Doxygen tool use to generate HTML based documentation.
-
===Resources===  
+
=== Team===
 +
* Dev: Thomas Preisler
 +
* Lead: Vladimir Voskresensky
-
BZ 178882 support C/C++ documentation tool Doxygen: https://netbeans.org/bugzilla/show_bug.cgi?id=178882
+
===Overview===
 +
# Use embedded Doxygen commands in source to supply code completion in editor with proper documentation.
-
Doxygen Tutorial http://www-scf.usc.edu/~peterchd/doxygen/
+
===Target User===
 +
Anyone using C/C++ editor and code completion (Steven, Leon).
-
Doxygen Tutorial http://class.ee.iastate.edu/cpre288/lectures_files/Doxygen%20Tutorial.pdf
+
===Typical Workflow===
 +
# User adds Doxygen commands to source files either manual or using generated template.
 +
# Code completion now shows proper documentation for classes, methods, etc. when invoked
===User View===
===User View===
 +
 +
====Doxygen Code Templates====
 +
Support commen Doxygen templates for easily adding Doxygen command to source files (see https://netbeans.org/bugzilla/show_bug.cgi?id=171326):
 +
 +
Before template expansion:
 +
/**|*/
 +
double abs(complex& a){ // magnitude of the complex number
 +
    return sqrt(a.real*a.real + a.img*a.img);
 +
}
 +
 +
After template expansion:
 +
/**
 +
  * Document abs(complex&) here...
 +
  * @param a
 +
  * @return ...
 +
  */
 +
double abs(complex& a){ // magnitude of the complex number
 +
    return sqrt(a.real*a.real + a.img*a.img);
 +
}
 +
 +
====Integration with Code Completion====
 +
Integrate html Doxygen docs with code completion. Code completion will automatically pick up the generated html documentation and present it in the code completion pop-up choice dialog like this:
 +
 +
[[File:codecompletion.jpg]]
 +
 +
To reproduce above scenario:
 +
# Open Fractal demo program
 +
# Position the cursor at line 86 in Fractal.cc, just above the abs function
 +
# Type "/**" and code model should add a "*/" to the comment.
 +
# With the cursor right after the 2nd star, hit return
 +
# Code model should add a Doxygen template you can fill out
 +
# Go to somewhere else in the code, for instance line 82, and type "abs" and then hit Ctrl+Space. Code completion should suggest abs(complex& a) and show your Doxygen comments in the dialog.
 +
 +
 +
[[File:codecompletion2.jpg]]
 +
To reproduce above scenario:
 +
# install man2htm (in /usr/bin)
 +
# type 'strl' and then hit Ctrl+Space
 +
 +
===Resources===
 +
 +
IZ:
 +
 +
https://netbeans.org/bugzilla/show_bug.cgi?id=178882
 +
 +
Tutorial:
 +
 +
http://www.stack.nl/~dimitri/doxygen/starting.html
 +
 +
http://www-scf.usc.edu/~peterchd/doxygen/
 +
 +
http://class.ee.iastate.edu/cpre288/lectures_files/Doxygen%20Tutorial.pdf
 +
 +
Project:
 +
 +
http://sourceforge.net/projects/doxygen/
 +
 +
http://www.doxygen.org
 +
 +
http://www.stack.nl/~dimitri/doxygen/
 +
 +
Latest sources:
 +
 +
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
 +
 +
I have started experimenting with documentation in C/C++ code completion. The code is in the pelmel project:
 +
http://kenai.com/projects/pelmel
 +
in the NB6.8 repository:
 +
http://kenai.com/projects/pelmel/sources/nb68/show
 +
in module "cnd"/"Extended C/C++ Editor". The module can be installed from this update center:
 +
http://lahoda.info/hudson/job/pelmel68/lastSuccessfulBuild/artifact/build/updates/updates.xml.gz
 +
Note that the module requires a very recent trunk build.
===Schedule===
===Schedule===
Line 19: Line 97:
!Content
!Content
|-  
|-  
-
| NB 6.9 M1 Release
+
| 1
-
| 2/24/10
+
| 1/18/10
-
|  
+
| User View Ready
|-  
|-  
-
| NB 6.9 Feature Freeze
+
| 2
-
| 3/08/10
+
| 3/15/10
 +
| Feature useful
 +
|-
 +
| 3 NB 6.9 M1
 +
| 4/07/10
|  
|  
|-  
|-  
-
| NB 6.9 Code Freeze
+
| 4 NB 6.9 Beta
-
| 4/16/10
+
| 4/15/10
-
| Done, all critical bugs fixed.
+
| Feature complete
 +
|-
 +
| 5 NB 6.9 Code Freeze
 +
| 5/10/10
 +
| Done, all P1/2 bugs fixed.
|}
|}

Current revision as of 05:42, 23 February 2010

Contents

CND 69 Doxygen

Doxygen commands are embedded commands in sources the Doxygen tool use to generate HTML based documentation.

Team

  • Dev: Thomas Preisler
  • Lead: Vladimir Voskresensky

Overview

  1. Use embedded Doxygen commands in source to supply code completion in editor with proper documentation.

Target User

Anyone using C/C++ editor and code completion (Steven, Leon).

Typical Workflow

  1. User adds Doxygen commands to source files either manual or using generated template.
  2. Code completion now shows proper documentation for classes, methods, etc. when invoked

User View

Doxygen Code Templates

Support commen Doxygen templates for easily adding Doxygen command to source files (see https://netbeans.org/bugzilla/show_bug.cgi?id=171326):

Before template expansion: 

/**|*/
double abs(complex& a){ // magnitude of the complex number
    return sqrt(a.real*a.real + a.img*a.img);
}

After template expansion: 

/**
 * Document abs(complex&) here...
 * @param a
 * @return ...
 */
double abs(complex& a){ // magnitude of the complex number
    return sqrt(a.real*a.real + a.img*a.img);
}

Integration with Code Completion

Integrate html Doxygen docs with code completion. Code completion will automatically pick up the generated html documentation and present it in the code completion pop-up choice dialog like this:

File:codecompletion.jpg

To reproduce above scenario:

  1. Open Fractal demo program
  2. Position the cursor at line 86 in Fractal.cc, just above the abs function
  3. Type "/**" and code model should add a "*/" to the comment.
  4. With the cursor right after the 2nd star, hit return
  5. Code model should add a Doxygen template you can fill out
  6. Go to somewhere else in the code, for instance line 82, and type "abs" and then hit Ctrl+Space. Code completion should suggest abs(complex& a) and show your Doxygen comments in the dialog.


File:codecompletion2.jpg To reproduce above scenario:

  1. install man2htm (in /usr/bin)
  2. type 'strl' and then hit Ctrl+Space

Resources

IZ:

https://netbeans.org/bugzilla/show_bug.cgi?id=178882

Tutorial:

http://www.stack.nl/~dimitri/doxygen/starting.html

http://www-scf.usc.edu/~peterchd/doxygen/

http://class.ee.iastate.edu/cpre288/lectures_files/Doxygen%20Tutorial.pdf

Project:

http://sourceforge.net/projects/doxygen/

http://www.doxygen.org

http://www.stack.nl/~dimitri/doxygen/

Latest sources:

http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

I have started experimenting with documentation in C/C++ code completion. The code is in the pelmel project: http://kenai.com/projects/pelmel in the NB6.8 repository: http://kenai.com/projects/pelmel/sources/nb68/show in module "cnd"/"Extended C/C++ Editor". The module can be installed from this update center: http://lahoda.info/hudson/job/pelmel68/lastSuccessfulBuild/artifact/build/updates/updates.xml.gz Note that the module requires a very recent trunk build.

Schedule

Milestone Date Content
1 1/18/10 User View Ready
2 3/15/10 Feature useful
3 NB 6.9 M1 4/07/10
4 NB 6.9 Beta 4/15/10 Feature complete
5 NB 6.9 Code Freeze 5/10/10 Done, all P1/2 bugs fixed.
Retrieved from "http://wiki.netbeans.org/CND69Doxygen"
Not logged in. Log in, Register

NetBeans Wiki
By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo