Optional expanded documentation

DrScott

Currently, methods are allowed only a single descriptive comment. Would it be possible to add an optional section for advanced documentation in the method definition dialog box? For example:

Method parameters - describe what they are
Method return vale - describe what it is
Preconditions that must be met
Postconditions that the method must adhere to
Invariants
Exceptions raised in the method
Other information, such as why the particular implementation was used

Thank you.

bgrommes

If the intent of the "single descriptive comment" is to be a summary to be picked up by things like "intellisense", then I agree that a separate place to put more detailed info (structured according to the developer's preferences) would be a good thing. Documentation tools could use this to produce rich documentation.

Perhaps markdown support would also be handy?

Garry

I'm all for thoroughly documenting a method which is part of the reason I including tool tip descriptions for every stdlib method but I'm reluctant to add an "advanced" description section to the metadata panel for a method. In part because that area is already quite large and adding another large text area or multiple fields will really eat into available space if expanded and add a lot of visual clutter to the bulk of users.

The current description text field is actually an auto expanding textarea so it's not constrained to a single line. What I've done as an interim measure is to support Markdown in the existing description textarea. That raw Markdown is not rendered in the method view but is rendered in two places:

(1). Hovertips for autocomplete:

(2). In the symbol information panel at the bottom of the IDE:

This will be in the next release: https://feedback.objo.dev/feature/425

Hopefully this is a happy middle ground compromise?

DrScott

Thanks, Garry. This is an acceptable middle ground. For the extra information I requested, what about a default template in Markdown that could be optionally added to the end of the Description field via a menu option, such as:

Parameters:
Parameter1- description of parameter here

Returns:
Return- description of return value here

Preconditions:

Postconditions:

Invariants:

Exceptions:

Implementation Notes:

It would be even better if the method’s parameters and return were added automatically by the IDE, but that may be asking too much.

Garry

I don't think I want to add a special menu action just for pasting in a template into a method description but perhaps adding a feature to add a snippet at the insertion cursor would be a better, more generic, solution? What I am considering is IDE scripting using ObjoBasic. Once that's implemented you could bind a keyboard shortcut you define to a script that inserts a markdown template at the cursor.