CND69Doxygen

(Difference between revisions)
(User View)
(Integration with Code Completion)
 
(35 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.
=== Team===
=== Team===
Line 8: Line 8:
===Overview===
===Overview===
-
# Support Doxygen at a similar level as Javadoc is supported by Java projects.
+
# Use embedded Doxygen commands in source to supply code completion in editor with proper documentation.
-
# Implement as plugin module using only public project SPIs/APIs.
+
-
# User builds and installs Doxygen application seperately. Doxygen is not distributed with NetBeans/CND.
+
-
# Integrate Doxygen with C/C++ managed projects in a similar fashion Javadoc is integrated with Java projects supporting project properties and a run action to generate the documentation files.
+
-
# No direct support for Doxygen for unmanaged projects
+
-
# Test and verify with Doxygen 1.6.2 available here http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
+
 +
===Target User===
 +
Anyone using C/C++ editor and code completion (Steven, Leon).
-
Questions:
+
===Typical Workflow===
-
# Is 2) possible?
+
# 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===
-
====Project Logical View====
 
-
No changes.
 
-
====Project Physical View====
+
====Doxygen Code Templates====
-
Default output to project ''dist'' folder
+
Support commen Doxygen templates for easily adding Doxygen command to source files (see https://netbeans.org/bugzilla/show_bug.cgi?id=171326):
-
  Project
+
Before template expansion:
-
  dist
+
  /**|*/
-
     Debug
+
double abs(complex& a){ // magnitude of the complex number
-
      GNU-MacOS
+
     return sqrt(a.real*a.real + a.img*a.img);
-
        doxygen
+
}
-
          html
+
-
          man
+
-
          richtext
+
-
          xml
+
-
          latex
+
-
====Make Target====
+
After template expansion:
-
Makefiles will have a new make target called ''doxygen'' so the Doxygen files can be generated from the command line.
+
/**
-
 
+
  * Document abs(complex&) here...
-
====Actions====
+
  * @param a
-
Managed projects will be have a new action called ''Generate Doxygen''. It will run doxygen on the project files with the specified parameter and generate the output files in the "dist" folder.
+
  * @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:
-
Questions:
+
[[File:codecompletion.jpg]]
-
# ...
+
-
====Project Properties====
+
To reproduce above scenario:
-
Many aspects of the generated doxygen files can be controlled by a set of configuration specific project properties. No details yet, but a good start is the settings from the Doxygen GUI frontend MacOS wizard from below. Not all properties are neccessary. Things like file suffixes are controlled by other properties. Here is a list of some of the more important ones:
+
# Open Fractal demo program
-
Project Name
+
# Position the cursor at line 86 in Fractal.cc, just above the abs function
-
Project Version
+
# Type "/**" and code model should add a "*/" to the comment.
-
Output Directory
+
# With the cursor right after the 2nd star, hit return
-
Output (HTML, LaTeX, Man, Rich Text, XML)
+
# Code model should add a Doxygen template you can fill out
-
Diagrams
+
# 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.
-
Perhaps also a catch-all  blank text field to specify any doxygen option similar to the ''Add Additional Options'' compilers and linker have. It is TBD exactly which properties will be directly supported by the GUI.
+
-
+
-
Questions:
+
-
#
+
-
===Typical Workflow===
 
-
# User adds Doxygen commands to source files
 
-
# He modifies the Doxygen project properties to suit he needs
 
-
# He runs the "Generate Doxygen" action from the project context menu
 
-
# He picks up the documentation in dist/.../doxygen
 
-
 
-
===Doxygen GUI frontend (Mac)===
 
-
[[File:doxygen1.jpg]]
+
[[File:codecompletion2.jpg]]
-
[[File:doxygen2.jpg]]
+
To reproduce above scenario:
-
[[File:doxygen3.jpg]]
+
# install man2htm (in /usr/bin)
-
[[File:doxygen4.jpg]]
+
# type 'strl' and then hit Ctrl+Space
-
[[File:doxygen5.jpg]]
+
-
[[File:doxygen6.jpg]]
+
===Resources===  
===Resources===  
Line 99: Line 82:
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
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 110: Line 101:
| User View Ready
| User View Ready
|-  
|-  
-
| 2 NB 6.9 M1 Release
+
| 2
-
| 2/24/10
+
| 3/15/10
-
|
+
-
|-
+
-
| 3
+
-
| 3/05/10
+
| Feature useful
| Feature useful
|-  
|-  
-
| 4 NB 6.9 Feature Freeze
+
| 3 NB 6.9 M1
-
| 3/08/10
+
| 4/07/10
 +
|
 +
|-
 +
| 4 NB 6.9 Beta
 +
| 4/15/10
| Feature complete
| Feature complete
|-  
|-  
| 5 NB 6.9 Code Freeze
| 5 NB 6.9 Code Freeze
-
| 4/16/10
+
| 5/10/10
| Done, all P1/2 bugs fixed.
| 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.
Not logged in. Log in, Register

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