[Q] How to add fields to a class

[Tieske]

trafficstars

considering this code;

-------------------------------------------------------------------------------
-- QueueItem class.
-- Object created by `worker:push` when data is pushed into the `worker` queue
-- @type queueitem

  local queueitem = {
      data = data,
      worker = worker,  -- worker thread table
      cancelled = nil,  -- set to true when cancelled
      completed = nil,  -- set to true when completed
  }
  -----------------------------------------------------------------------
  -- Cancels the queueitem.
  -- When cancelling both the `cancelled` and `completed`
  -- flag will be set. The cancel flag will prevent the data from being executed
  -- when it is being popped from the queue.
  -- @see queueitem
  -- @see worker.push
  function queueitem:cancel()
      self.cancelled = true
      self.completed = true
  end

  -- Completes the queueitem.
  -- The `completed` flag will be set.
  -- @see queueitem
  -- @see worker.push
  function queueitem:complete()
      self.completed = true
  end

  return queueitem
end

I would like the fields data, worker, cancelled and completed to be documented. I tried adding @field tags to the section header (around @type queueitem) but that didn't work.

How can I deal with this?

[andrewstarks]

I really wish that you would stop articulating my issues, months before I have them! It makes it annoying to have to realize that my issue is a duplicate! :) Just jokes, man.

Anyway, this is a more rambling version of the above issue. Since it took me a good 15 minutes to write it, and it may provide a separate perspective, I'll paste it here. Just understand that it all boils down to: "Yeah. What he said!"

I have a C module. It has a "class". For the methods, there are functions that I'm documenting, and that works well.

However, the options for the module are accessed by simply using a field, such as s.linger. Setting is done in a similar manner: s.linger = 1000.

To accomplish this, I use an accessor struct that uses a handful of functions that deal with different scenarios (-1 == false, 0 = true, string values, etc). So there is no 1-1 relationship between functions and fields and no function calls to go with them, anyway.

My question is, how do I designate field properties for types/classes? I've tried:

/***
A nanomsg socket userdata object.
@type socket 
@field domain The socket domain (raw or full socket) (read only)
@field protocol The protocol that the socket was created with (read only)
...
*/

But that doesn't work. I don't have a separate table to refer to... I think that I'm going to make a new topic and just refer people over to it.

Instead, I'd like to list field properties for the object near/along with/as a sub section next to the methods for the clas...

Am I missing something?

[andrewstarks]

Hey @stevedonovan,

In response to your suggestion, I'm using:

///The socket domain (raw or full socket) (read only)
//@table domain


///The protocol that the socket was created with (read only)
//@table protocol


///The time that a socket tries to send pending outbound messages after close has been called, in milliseconds. A false value (`false` or `nil`) means infinite linger. Default value is 1000 (1 second).
//@table linger 

This results in a document that looks readable. It's not quite as nice as formatting it the same way as another field would be, but it's good enough for now.

Thank you for your help! If I get a chance, I may poke around ldoc and see if there is a way that I can add some kind of patch.

[stevedonovan]

Yeah, calling a property a 'table' is a real hack and I will look at why we can't just use 'field' in this situation.

The manual says that 'field' is a valid module-level (or section-level) tag but a quick experiment reveals this is to be (currently) a lie.

[andrewstarks]

I'm not sure if I'm doing this wrong, or not...

Using this method, I have a reference, such as @{reconnect_interval}, which points to a previous //@table reconnect_interval entry in the same class/type. My understanding is that this should work. However, it does not. I need to use @{socket.reconnect_interval} for it to see the reference. It doesn't seem possible to get around this, and so my references show up fully qualified, instead of the shorter version.

My apologies if I'm misunderstanding how this works.What is the correct way to scope references?

--Andrew

[stevedonovan]

I see the problem - scoping of references is not working as promised within classes, only within ye olde modules.

[andrewstarks]

Hey Steve,

I went to see if this was fixed and did see some improvement.

You may already know where you are at on this, but in case that you don't....

In C:

/***
A nanomsg socket userdata object.
@type socket 
@field domain The socket domain (raw or full socket) (read only)
*/

This does not work. The fields do not appear.

/***
A nanomsg socket userdata object.
@type socket 

*/

///The socket domain (raw or full socket) (read only)
//@field domain 

Does work, EXCEPT that the entry looks something along the lines of:

---

socket.domain

The socket domain (raw or full socket) (read only)

• domain:

---

So far as I can see, it looks like ldoc is starting a parameter list with the field name and then putting nothing after it, because there is nothing. Deleting it would be the correct move, I would think.

Also, types, read only fields legal values... these are all things that one might want to communicate. Not a biggie if they're not there. Just sayin' is all. :)

[Tieske]

I just tried the new release, to close this issue. But I can't seem to get the fields to display in the output;

The code:

local newqueueitem = function(data, worker)

-------------------------------------------------------------------------------
-- QueueItem class.
-- Object created by `worker:push` when data is pushed into the `worker` queue. This 
-- object can be tracked for progress or cancellation.
-- @type queueitem
-- @field cancelled flag; `true` when the element has been cancelled
-- @field completed flag; `true` when the element has been completed or cancelled ('completed' is when the worker requests the next element by calling its `pop()` function
-- @field worker The worker table for which this queue element has been enqueued.
-- @field data the actual data
-- @see worker.push

  local queueitem = {
      data = data,
      worker = worker,  -- worker thread table
      cancelled = nil,  -- set to true when cancelled
      completed = nil,  -- set to true when completed
  }
  -----------------------------------------------------------------------
  -- Cancels the `queueitem`.
  -- When cancelling both the `cancelled` and `completed`
  -- flag will be set. The `cancelled` flag will prevent the data from being executed
  -- when it is being popped from the queue.
  function queueitem:cancel()
      self.cancelled = true
      self.completed = true
  end

  -----------------------------------------------------------------------
  -- Marks the `queueitem` as completed.
  -- The `completed` flag will be set. Generally there is no need to call this method, it will
  -- be called when the `worker` handling this element pops the next element from its queue.
  function queueitem:complete()
      self.completed = true
  end

  return queueitem
end

The output:

The fields don't show. Am I missing something?

[stevedonovan]

Sorry, Thijs - I should explain things better. Basically the @field must be in a separate doc item - the @type is still basically a section and not an item per se. (Although I must admit that what you are doing is much more logical!)

This example might help: https://github.com/stevedonovan/LDoc/blob/master/tests/styles/type.lua

Both a subtable and a field, which uses one of the standard typed aliases.

[Tieske]

I think I got it now. Any chance to add the 'more logical' variant? if not, that's fine by me and then I'll close this issue.

[stevedonovan]

It would be a special-case, so I need to think about it - it can be done. It is of course less general than having properties/fields/whatever as separate items but it is ... more logical. And therefore easier to document ;)

[Tieske]

I'll leave the issue open for now, but feel free to close it anytime you feel like it.