Improved PCL documentation

[georg.viehoever]

Hi,

the PCL documentation that comes with the PCL distribution of PixInsight is generated using a tool called doxygen. Its operation is controlled by a configuration file. I have created a doxygen.conf file that produces much more comprehensive documentation than the default one. Some features:

- allows to navigate into the source files
- includes a search field for finding classes and members (on the top right)
- also parses the Javascript headers (.jsh)
- also parses the example files in src (C++ and Javascript)
- contains a lot more indices, e.g. per file or directory
- contains a lot more cross-references, e.g. which function is used in which example (sometimes quite helpful to find example code).

Here is how to use:

- copy doxygen.conf as attached to your PixInsight installation (the directory that includes bin, src, include, ...)
- call "doxygen doxygen.conf"
- browse to "firefox myDoxygenDoc/html/index.html"
- tested on Fedora11 with Development profile. If doxygen is not available on your system, just install it using "Add/Remove Software..."
- the config file should also work with a Windows or Mac installation of doxygen, see http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc. However, I did not test this.

Juan: If you like you can use/adapt it for future PixInsight releases.

Georg

[Nocturnal]

This sounds really great Georg, thanks!

[Juan Conejero]

Hi Georg,

Thank you for the updated Doxygen configuration file. I have added some of the features you mention to improve PCL documentation with more corss references, full headers source code and better graphics.

For reference, I have attached my working Doxyfile, which I am using to produce the official documentation of the next PCL version.

Just a note. To generate graphics with Doxygen, the graphviz package must be installed. For example:

su -c 'yum install graphviz'

on any yum (RPM) based Linux box.

[georg.viehoever]

Sounds great  I can't wait to see the next release....
Georg

[mmirot]

Where is the the PJSR documentation found?

Max

[Nocturnal]

On windows there's a link in the start menu. In my case:

file:///C:/PCL64/doc/html/index.html

[mmirot]

On windows there's a link in the start menu. In my case:

file:///C:/PCL64/doc/html/index.html

I am confused. Is n't this the C++ documentation ? 

Max

[Nocturnal]

Sorry, I read the topic (PCL) instead of your question. I don't think there is any online readable PSJR documentation. The class browser provides an itty bit of info but nothing sufficient. As you know Juan likes coding but loathes documentation. At some point that's going to hinder the adoption of PI but it's going to take some doing before this changes I'm afraid. There's always one more feature to implement.

Last year when I announced I was going to speak at MWAIC I really hoped I'd be able to say there is documentation for PI when the inevitable question comes on Friday. Unfortunately with only a few days remaining, we are where we were then.

[mmirot]

Thanks

I look forward to meeting you.

Max

[Nocturnal]

Same here Max

[NKV]

Hi guys.

Please try to search in the PCL documentation: "Exists".
I have got answer: "No Matches" 

I just forgot how to check if a file exists.
I finally figured out how to do it, but spent a lot of time ...

Why search is not successful?

[georg.viehoever]

No idea. Doxygen (the document generator) is sometimes a bit special  . Searching for "file" works: http://www.pixinsight.com/developer/pcl/doc/html/File_8h_source.html

Georg

[NKV]

No idea.

Georg, thanks.
I know about "file.h", but for me interesting how many such useful function is not included in PCL documentation.
I mean, it's not good idea to search manually inside every "*.h" especially if I don't know name of function or I don't know how it realized in PCL.

[Juan Conejero]

Why search is not successful?

Because File::Exists() is a static member function. This seems to be a limitation of Doxygen. All non-static members can be found without problems; for example, search for "EnableAntialiasing" and it finds it in the pcl::GraphicsContextBase class. Sorry...

[georg.viehoever]

Hi Juan,
In other code that I am writing doxygen correctly extracts static functions.

could you check the following two things:
1. the setting of the EXTRACT_* configuration. See following excerpt from http://www.stack.nl/~dimitri/doxygen/config.html:

Code: [Select]

EXTRACT_ALL
If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in documentation are documented, even if no documentation was available. Private class members and static file members will be hidden unless the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES

Note:
This will also disable the warnings about undocumented members that are normally produced when WARNINGS is set to YES

EXTRACT_PRIVATE
If the EXTRACT_PRIVATE tag is set to YES all private members of a class will be included in the documentation.


EXTRACT_STATIC
If the EXTRACT_STATIC tag is set to YES all static members of a file will be included in the documentation.
2. Error messages generated by doxygen. The sometimes hint at possible sources of an issue (which can be as simple as a missing #define).

Georg