mgalloy / idldoc Goto Github PK
View Code? Open in Web Editor NEWDocumenting IDL code
License: Other
Documenting IDL code
License: Other
There are invalid ENTITY directives in the !DocBook output when there are files in the top-level directory.
The first sentence of the descriptions of files, routines, and parameters should be used to annotate entries in the index.
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.
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'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.
Oh, those greens are gross, Galloy. I'll take a crack at a new color scheme, if you'd like.
mp
In File attributes paragraph, Modifcation date
might be replaced by Modification date
.
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.
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.
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).
Could you please use
COMPILE_OPT hidden
on the internal IDLdoc routines? They're clogging up my HELP output!
Thanks!
There should be an flag to set that would report on "suspicious" code.
Suspicious would include:
Add an advanced search on the search tab where criterion such as: categories, author, parameters, etc. can be specified separately.
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).
The chromocoding for the source code link should style:
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.
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...
It would be nice to get decent coverage of at least the underlying libraries:
Suggested syntax:
:Properties:
propname : type=string
name of the property
@property propname {type=string} name of the property
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.
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.
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' {} \;
The rst markup was only partly implemented for IDLdoc 3.0. Missing markup that should be implemented:
* lists (numbered, bulleted, and definition)
* *emphasis* and **bold**
* inline ``code``
* links: single word and phrase links (HTML and internal links)
* images
* tables
There is other markup that is not as important for header documentation that could also be implemented for a separate ticket later.
Anything going to doc_system::warning should be remembered and set to a "Runtime warnings" section during output.
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:
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.
To accomplish this:
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.
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.
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
There should be a context menu item for projects which brings up a dialog which allows parameters of the IDLDOC call to be set.
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.
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...
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:
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.
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.
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.
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.
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 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).
This section should include:
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.
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.
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.
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.
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).
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.
Let's use the new IDL 7.0 icon from the IDL resource/bitmaps directory for the IDLdoc icon.
IDLdoc should allow unrecognized headers as standard file/routine attributes and pass them through into the documentation. This request was originally from #51.
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?
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.