Feature #737

Sorting automatic documentation out

Added by kju over 6 years ago. Updated about 6 years ago.

Status:Closed Start date:03/26/2009
Priority:Normal Due date:
Assignee:Spooner % Done:

100%

Category:-
Target version:v0.1.0
Component: Affected Version:
Close Reason:

Description

As we talked in relation to function library and rdoc.

History

Updated by Spooner over 6 years ago

I feel that generating rdoc documentation is pointless until we have a way to load embedded pages without sending it manually via Sickboy.

A simple parser that generates RM wiki code might be better, but would require some manual copy-and-paste into the actual pages. Not going to do anything yet though, until we get some stuff sorted out.

Here is the proposed format, which is basically what I use for my function headers already:

// --------------------------------------
// Function: FROG_wobble
//
// Access: Public/Private
//
// Description:
//   yada yada
//   fubar cheese nimblepumpkin
//
// Parameters:
//   0: _fish - description [Type]
//   1: _cheese - description [Type]
//     0: _first - Description [Type]
//     1: _second - Description [Type]
//
// Returns:
//   description [Type]
//
// Example(s):
//   Description1
//   [sqf]
//   _frogs = [12, [4, 5]] call FROG_wobble;
//   [/sqf]
//
//   Description2
//   [sqf]
//   _frogs = [12, [99, -1]] call FROG_wobble;
//   [/sqf]
// --------------------------------------

Function is required, since it isn't possible to assume the name of the function being documented. It will also initiate parsing until there is a break in the documentation block.

Access is a new heading, which I've not used before, and is intended to allow API (just public) or internal (public + private) documentation to be generated.

To save effort, I'll enforce use of // rather than /* */ since it is just extra parsing effort and I can't be bothered.

This would produce a page like this:

FROG_wobble

Access

Public

Description

yada yada.
fubar cheese nimblepumpkin.

Parameters

0: _fish - description [Type]
1: _cheese - description [Type]

0: _first - description [Type]
1: _second - description [Type]

Returns

description [Type]

Example(s):

Description1

1 _frogs = [12, [4, 5]] call FROG_wobble;

Description2

1 _frogs = [12, [99, -1]] call FROG_wobble;

Updated by kju over 6 years ago

Yep I meant that as we discussed last time. Sorry for not being straight.

This is what I used for the function library for now:

#define fGetPosASL

// #docstart
//
// @description
//    Gibt die absolute Position (mit Hoehe ueber dem Meeresspiegel) eines Objekts or einer Position aus (above-sea-level).
// @syntax
//    object call fGetPosASL
// @parameters
//    0: Objekt: object or array - Es kann entweder ein object or eine Position angegeben werden.
// @returns
//    array - Die absolute Position
// @example
//    0: Flugzeug call fGetPosASL
//       [300, 1200, 50] call fGetPosASL
//
// #docend

That said I believe examples should be dropped as examples are to be found in the tests.

Updated by Spooner over 6 years ago

GUI commands cannot easily be tested in that way, and tests should be exhaustive (rather than exemplary).

@syntax is superfluous, since it can be determined from @parameters and @function.

docstart and docend are superfluous. Doc checking can start at the first tag (function: or @function) and go on until the comment ends. At the most, if you are really being anal, you could have endfunction (since function is required at the start for the automated reader to know what function to document anyway).

I still think you need an @access tag, since some commands want to be documented only in internal documentation (private) and some want to be documented only in external documentation (public).

Updated by kju over 6 years ago

You got me wrong Spooner. The given one was only to show what I have atm.
It was NOT a suggestion.

@syntax is superfluous, since it can be determined from @parameters and @function.

Hm not sure. Would copy & paste easier.
Yet most likely you are right. DRY for the better!

docstart and docend

Yep. Only used to mark the area for now for future conversion.

Updated by Spooner over 6 years ago

Sorry, yes, I was likewise only making alternative suggestions, not demands.

Actually though, now I think about it, a @syntax does make sense, since it allows for more control, especially when arrays are used:

[_frog, [[_cheese, _peas], ...], [_fish, ...]] call myfunc;

For this, I'd want to document it like this:

  0: _frog [String]
  1: _nobblies [Array of Array]
    0: _cheese [String]
    1: _peas [Number]
  2: _wobble [Array of String]

Both so slightly different information, so need to be both there (or the information format needs to be cleaned up to allow DRY).

Updated by Spooner about 6 years ago

  • Project changed from DevHeaven (Only site issues) to Community Base Addons

Updated by Spooner about 6 years ago

  • Priority changed from Low to Normal
  • % Done changed from 0 to 80

Possibly needs better explanation, but I've implemented automatic documentation for functions (assuming they follow the function file naming convention and have header info)

Updated by kju about 6 years ago

Good job. Good explanation page. It would be good to link the actual
online html docu once available.

Updated by Sickboy about 6 years ago

  • Target version set to v0.1.0

Updated by Spooner about 6 years ago

Added macro documentation (for my macros only; I'll leave sickboy to document his own at a later date!). ef53d191

Updated by Spooner about 6 years ago

  • Status changed from Assigned to Resolved
  • % Done changed from 80 to 100

Everything that needs to be documented is documented and in at least a reasonable way. More can be added after initial release.

Updated by Sickboy about 6 years ago

  • Status changed from Resolved to Closed

Looks good

Also available in: Atom PDF