Support for documenting Model fields

[nene]

Would be nice if one would only need to write this:

fields: [
   /**
    * Long description.
    */
   { name: 'description', type: 'string' },
   /**
    * Value of the item.
    */
   { name: 'value', type: 'string' },
   /**
    * True if active.
    */
   { name: 'isActive', type: 'bool' }
]

...and all the fields would get documented as config options.

The data types should be mapped as follows:

• auto - Mixed
• string - String
• int, integer, float, number - Number
• bool, boolean - Boolean
• date - Date

[jratcliff]

This would be nice to have when documenting custom apps

[gregjacobs]

+1

This would be very useful for our documentation. Models are at the center of every application, and being able to easily reference the fields that they define would be great. Currently, developers have to view the source of a model from the docs to discover what fields exist.

[dhurlburtusa]

+1

I hack the documentation for fields by using property tag. It would be very nice to have an actual field tag.

[incutonez]

I've created a Ruby script that adds a Fields tag to the documentation... it was created in haste, so please, make fun of me if it's no good, haha. Anyway, this is the Ruby script:

fields_tag.rb

require "jsduck/tag/member_tag"

class Field < JsDuck::Tag::MemberTag
  def initialize
    @tagname = :field
    @pattern = "field"
    @member_type = {
      :title => "Fields",
      :position => MEMBER_POS_CFG - 0.1,
      :icon => "fields.png"
    }
  end

  def parse_doc(scanner, position)
    tag = scanner.standard_tag({
        :tagname => :field,
        :type => true,
        :name => true,
        :default => true,
        :optional => true
      })
    tag[:doc] = :multiline
    tag
  end

  def process_doc(context, field_tags, position)
    p = field_tags[0]
    # Type might also come from @type, don't overwrite it with nil.
    context[:type] = p[:type] if p[:type]
    context[:default] = p[:default]

    # Documentation after the first @property is part of the top-level docs.
    context[:doc] += p[:doc]
    context[:name] = p[:name]
  end

  def to_html(field, cls)
    member_link(field) + ': ' + field[:html_type]
  end
end

Take note of the :icon variable... either delete that bit or include an icon image with that name. Then to mark your code, it's set up exactly like the property tag, so just do something like /** @field {string} name */. It's not ideal, but it's better than nothing. Also, when you run jsduck, don't forget to include --tags fields_tag.rb.

[valioDOTch]

+1 I'd like to see a proper Model field documentation handling as well.

[priestj]

+1 Please add, we have hundreds of models, this would really be a useful.

[garytaylor]

+1 Ive used the workaround above for now, but would like to see this

[alberto-chiesa]

+1 I'm sorry I can't upvote @incutonez comment. THANKS!

The @field tag Works perfectly even on Windows. I'm just gonna need a little extra bit for actually including a field description, but it's already fine as it is.

I think the suggested implementation could almost go straight into the codebase. It doesn't give us a perfect, smart, implementation, but at least lets us properly separate fields from other elements.

In my case, I'm going to auto-generate the model classes from server side anyway, so the extra typing is not really an issue.