mgalloy / idldoc Goto Github PK

The following code:

;+
;  @uses utility_compile
;-

PRO context_data__define

   struct = {context_data, $
            ping_key:"", $
            recorder_key:"" , $
            target_key:"", $
            display:"" }

end

produces this error:

Parsing eti_analysis_update.pro...
IDLDOC: cannot construct definition for class context_data

I am not sure if this error is valid, or if it is why. It wasn't produced under IDLDoc2.0.

It may be due to the use of the @uses tag?? That has used with previous versions to track dependencies, but normally intended for the file level.

It would be nice to get decent coverage of at least the underlying libraries:

• templating,
• textmarkup,
• math,
• collection, and
• util packages.

McCabe complexity statistics (McCabe cyclic, McCabe essential, McCabe modular design) were computed in the IDLdoc 2.0 code base. This functionality should be added to the IDLdoc 3.0 code base, though possibly in a simplified manner (i.e. reporting just one number).

Also, there should be user-defined limits for marking a routine as "complex" on the warnings page.

References for more information about the McCabe complexity statistics:

• McCabe pdf
• Cyclomatic complexity
• Complexity metrics

Oh, those greens are gross, Galloy. I'll take a crack at a new color scheme, if you'd like.

mp

I'm not sure if all tags should be allowed to have multiple copies or just special tags. Restrictions and author are two that seem like they should allow multiple tags. The behavior here should probably be to append to the current value of the tag.

Other tags should give a warning if used twice, such as the boolean tags like abstract, obsolete, etc.

I noticed some discussion in the mailing list about multiple tags. My preference would be to have comments that come with the @uses tag accumulate into a list. (Right now the last one is used.) For example:

;  @uses utility_compile
;  @uses star_list_compile
;  @uses widget_compile
;  @uses algorithm_manager_compile
;  @uses resample_compile

would result in a comma delimited list rather than just resample_compile.

The advantage would be that used items / dependancies can then be more clearly seen and changed in the code too.

In the help generated by IDLDoc there is an error in the attributes section. I believe that the line:

required    in      Indicates argument is required.

should read:

required    required    Indicates argument is required.

The following code:

;+
;  uses utility_compile,multi_element_compile
;-

@time_series_data_model
@analysis_cache
@analysis_cache_support
@star_eti_analysis_subject
@processing_module_link

;+
;  Description: Handles user window selection and starts up the
;  multi_element_image_canvas window
;
;  @author: Chris Widdis
;  @field image_parent_widget An object containing the main base
;   widget
;  @field button_panel_id The widget id of the button panel
;  @field data_model_obj The data model object
;  @field data_nav_handle Handle of the data navigation settings.
;   Data navigation is not implemented, but would be simple to do so
;  @field multi_element_image_canvas Object reference to the
;   multi_element_image_canvas
;  @field analysis_cache_handle Handle of the cache where the requests
;   are stored when suspend analysis is pressed
;  @field display_output_handle Handle to the file output structure
;  @field caller_handle Handle of the one responsible for cleaning up
;   the analysis window
;  @field notify_procedure string of the function used to notify the
;   caller_handle it has closed.  It has the form:
;   pro notify_procedure, caller_handle
;-
PRO multi_element_analysis_window_settings__define
  struct = { multi_element_analysis_window_settings, $
             image_parent_widget:obj_new(), $
             button_panel_id:0L, $
             data_model_obj:obj_new(), $ 
             data_nav_handle:0L, $
             multi_element_image_canvas:obj_new(), $
             analysis_cache_handle:0L, $
             display_output_handle:0L, $
             caller_handle:0L, $
             notify_procedure: "" }
END

results in the following errors:

 Parsing multi_element_analysis_window.pro...
IDLDOC: cannot construct definition for class multi_element_analysis_window_settings
IDLDOC: invalid field image_parent_widget
IDLDOC: invalid field button_panel_id
IDLDOC: invalid field data_model_obj
IDLDOC: invalid field data_nav_handle
IDLDOC: invalid field multi_element_image_canvas
IDLDOC: invalid field analysis_cache_handle
IDLDOC: invalid field display_output_handle
IDLDOC: invalid field caller_handle
IDLDOC: invalid field notify_procedure
  Parsing multi_element_analysis_window_constants.pro...

Doctests are simple tests embedded in the documentation.

Inside a "tests" tag, any line that starts with "IDL> " would be executed and the output compared to the following line(s) that don't start with "IDL> ".

For example:

;+
; Factorial function.
; 
; :Tests:
;    IDL> a = factorial(5)
;    IDL> print, a
;        120
;-

The commands in a single :Tests: tag should run in a single scope (so the a variable above is seen by the second command).

I use IDL style documentation in my code and, for the most part, am delighted with the organization that IDLdoc brings to that documentation. However, two aspects of my commenting are consistently handled poorly by IDLdoc:

1. Deliberate use of whitespace (for example, adding a newline between each revision under the MODIFICATION HISTORY header, or including lists / indented code snippets in the PURPOSE header). IDLdoc deletes the whitespace when parsing, and lumps this text together in a rather ugly looking paragraph.

2. I sometimes include my own headers, in addition to the ones recognized by IDLdoc (like PURPOSE or INPUTS, etc). IDLdoc lumps these blocks of text into the PURPOSE header, ignoring newlines, etc.

Personally, I would really appreciate it if IDLdoc preserved newlines when parsing comments. In addition, if it finds a header that it doesn't recognize (i.e. any capatalized text ending in a colon and separated by the initial semicolon by one space), it should create a section for it in the IDLdoc output, and copy its contents verbatim (preserving whitespace). This would greatly enhance IDLdocs flexibility when using IDL style comments.

It would be helpful to have a link directly to the portion of the source code that a function refers to. Right now we can access the source code from the html output, which is fantastic, but - especially where a file contains many functions - it would be useful to be able to jump directly to the source for the function to save time searching. I am not sure of what this would take in terms of effort, but consider it low to medium priority (i.e. it would improve efficiency some and make IDLDoc nicer to use, but isn't preventing users from accessing all that they need now - in my humble opinion).

There should be a context menu item for projects which brings up a dialog which allows parameters of the IDLDOC call to be set.

Using the left navigation panel, navigate to a subdirectory in the "dir_files" frame, then open a file. The file will open up a new tab instead of in the "main_files" frame. This doesn't happen if the "dir_files" frame is all_files or "./".

This happens in Firefox, not Safari.

There should be a mechanism to allow "directory level" comments. In version pre-3.0, a file named directory-overview in the directory contained the directory overview comments, but the feature was broken in several of the releases. Some file and routine level tags would make sense of the directory level, such as copyright, history, author.

I think that there is a problem when IDLDoc tries to construct a class definition for a class that just inherits. For example:

pro star_course_vs_time_receiver_request`__`define 
  struct = { star_course_vs_time_receiver_request, $ 
             inherits star_single_receiver_request } 
end

Produces the following error:

IDLDOC: cannot construct definition for class star_course_vs_time_receiver_request

This doesn't seem to happen all of the time, but I can't find a consistent thread to indicate when this problem occurs and when it doesn't.

The following code

;+ 
; This procedure parses echo repeater delay information from the 
; NAD. It is expected to be found in the NAD/targets directory. The 
; file should be of the form:: 
; 
;     DELAY 
;     BUSTER 
;     DD-MMM-YY HH:MM:SS.sss Delay(s) 
;     29-JUL-07 13:49:15 2.500 
;     29-JUL-07 17:13:53 2.500 
;     29-JUL-07 17:50:13 4.000 
; 
; @pre This function requires that the following folder structure be ; in place: NAD/targets/*.txt 
; @author Joe Hood, Akoostix Inc. 
; @todo modify other parsers to use this pattern which requires much 
; less code and change log to use a star_log 
;- 
PRO parse_repeater_delays

Isn't generating the expected code block. In fact the whole top portion ends up looking like one paragraph in the html.

If a property is listed twice in the file comments for a file defining a class, one of the properties will be leaked (and not used in the output). Instead, the second instance of the property should find the first and tack on its comments to the firsts.

Routine descriptions could be expanded as needed. The syntax for each routine would be shown, but details would be shown if a phrase or icon was selected.

This should not be the default set of templates because of the reliance on Javascript.

IDLdoc should allow unrecognized headers as standard file/routine attributes and pass them through into the documentation. This request was originally from #51.

Tabs can be converted to an equivalent number of spaces. IDLdoc should have a keyword to specify the number of spaces for a tab.

A !DocBook set of templates would be useful for including in books. Use xinclude to create one large document from all the individual documents.

Anything going to doc_system::warning should be remembered and set to a "Runtime warnings" section during output.

It's not clear how idldoc "warnings" are defined. I can execute idldoc on a set of routines and the IDL output log window will say "0 warnings generated". However, in the idldoc-warnings.html file that's created, I may have a number of files listed with partial or no documentation. I use the latter file quite a bit to make sure my comments are consistent with my code. Maybe there needs ot be a separate category name for items that are warnings of a different type. It'd also be nice if there was more detail when documentation is only partial, for example, "missing keyword description" or "missing return value description". Those are the two most common I run across.

Keywords in the IDL format should not be optional by default. Not sure how how, or if, keyword would be marked, but it is possible to have required keywords.

There are invalid ENTITY directives in the !DocBook output when there are files in the top-level directory.

If there is an extra line between the IDLDoc information and the procedure definition for the first (just first?) function in a file, the IDLDoc information is assumed to be at the file level rather than function level. This type of markup worked in IDLDoc2.0, so it is assumed to be in error.

Example of code that would cause a problem:

;+
; IDLDoc comments
; @param variable (in} a variable
;-

PRO name, variable

variable = 2

end

This would give an error like:

IDLDOC: routine level tag 'param' at file level in blah.pro

To accomplish this:

• the LaTeX textmarkup class needs to be updated
• a set of LaTeX-based templates for all the current templates needs to be created
• the LaTeX templates need to include each other (starting with index.tt) so that they produce a single document

This section should include:

• how to use the template object
• what variables are available in which templates
• how to use TEMPLATE_PREFIX and TEMPLATE_LOCATION
• how to add another output type, creating an output class and using COMMENT_STYLE

Let's use the new IDL 7.0 icon from the IDL resource/bitmaps directory for the IDLdoc icon.

Overview files in the IDL format should look like:

Overview comments.

DIRECTORIES:
  ./: Description goes here. This must be followed by a blank line.

  collection/: Description goes here. Note that the description can flow
               onto following lines. It is the blank line that delimits
               directories.

The IDL Assistant will not be included in the IDL distribution for much longer, so there is not much point in generating output for it.

There should be a mechanism for adding comments for a DLM. This should allow for output documentation that looks similar to normal IDL code (but marked as DLM, of course), documenting params, keywords, return values, etc.

It would be useful to document what is required to reach "full documentation" status (as used to pull information into the warnings page). It would also be useful to be able to define or reduce the requirements for full documentation if it is more than just documenting all fields, param, keywords (i.e. the obvious required elements).

There should be an flag to set that would report on "suspicious" code.

Suspicious would include:

1. lack of compile_opt strictarr

Currently, the search phrase is currently found "as a phrase" instead of as individual words (that might be in separate locations in the item). It would be better if items that had each word in the phrase, but not necessarily together, were also found.

It would be very useful if indexing was only performed on files, classes, and routines. For large code bases including parameters, fields, and keywords can make the index too large to be usable.

I used the following to find and remove all lines with @inherits in them. This appears to be a safe option to deal with the resultant warnings. My understanding is that inheritance is automatically found from the IDL code now.

# in every *.pro file find lines with @inherits and delete them
find . -type f -name '*.pro' -exec sed -i '/@inherits/ D' {} \;

IDLDoc2.0 implied that @file_comments could be used at the start of a file and not just in routine comments. (Help indicated it to be "file level" comments)

In IDLDoc3.0 it seems implied that the initial (non-tagged) text at the file level should be treated as file comments. I suggest that if the tag @file_comments is present that it should also treat the following text as file comments. This would avoid potentially needless correction of previous documentation.

It would be helpful if there was a tree view in the IDLDoc directories (produced when you view html frames on the output). A tree view would allow users that have files in many subdirectories to collapse or expand the view for quicker browsing. I suggest that the default be to show the collapsed view. I am not sure of what this would take in terms of effort, but consider it low to medium priority (i.e. it might improve efficiency some and make it nice to use, but isn't preventing users from accessing all that they need now - in my humble opinion).

The chromocoding for the source code link should style:

• highlight headers (pro/function routine_name and parameters)
• literal strings

The first sentence of the descriptions of files, routines, and parameters should be used to annotate entries in the index.

Add an advanced search on the search tab where criterion such as: categories, author, parameters, etc. can be specified separately.

It would be very helpful when browsing documentation if we could specify related functions, classes, etc. to look at for more detail. IDLDoc already does a great job of linking in the class hierarchy, but it would also be useful if we could do this manually in some cases. This is especially useful where the _REF_EXTRA keyword is used for keyword inheritance. The best place to add this option might be where the @uses parameter is used.

Create a "man page" front end for IDLdoc that, given an individual routine name, would output the documentation for that routine.

The syntax for it would be something like:

  IDL> man, 'idldoc'
  /Users/mgalloy/projects/idldoc/trunk/idldoc/src/idldoc.pro

  idldoc, root=string [, output=string] [, /quiet] [, /silent] [, n_warnings=long] 
    [, log_file=string] [, /assistant] [, /embed] [, overview=string] [, footer=string] 
    [, title=string] [, subtitle=string] [, /nonavbar] [, /nosource] [, /user] [, /statistics] 
    [, format_style=string] [, markup_style=string] [, comment_style=string] 
    [, /preformat] [, /browse_routines] [, template_prefix=string] 
    [, template_location=string] [, charset=string] [, error=long] [, /help] [, /version]

  Generate documentation for IDL code. This is a wrapper routine for the doc_system 
  class; this routine only handles errors, saving/restoring !path, and creating the 
  doc_system object.

  etc...

Inputs and outputs, return value, etc. for a file level comment before any routine should be associated with the last routine in the file.

This is an attempt to parse/output more of the comments for code in the lib directory of the IDL distribution.

In File attributes paragraph, Modifcation date might be replaced by Modification date.

Suggested syntax:

:Properties:
  propname : type=string
    name of the property

@property propname {type=string} name of the property

Currently in IDLdoc, the OUTPUT keyword allows a user to put the documentation for IDL source code in a separate directory; however, a copy of each '''.pro''' file is also placed in the output directory. I'm OK with this as a default, but it would be nice to have the option of linking the HTML files in the output directory back to the '''.pro''' files in the source directory. Maybe a NO_COPY keyword?

Could you please use

COMPILE_OPT hidden

on the internal IDLdoc routines? They're clogging up my HELP output!

Thanks!