Documenting Properties in Types

[Tokazama]

@properties is nice for extending the getproperty and setproperty! functionality but it would also be nice if this could be extended to document a specific type's properties. Then we could have something like property_documentation(T) for some type T that could be called in a docstring for T and easily keep track of assigned properties.

Take the following example:

struct MyType
   "This is field 1"
    prop1
end

"This is property 1"
@defprop Prop1{:prop1}

@properties MyType begin
   prop1(self) => :prop1
   prop2(self) -> self + 2
  prop3(self) => :prop1
end

We have two problems here:

1. We can't be sure if what's being defined refers to a special mapping (like prop2 where the type is just mapping to another function or prop3 which maps a different property name to the field prop1) or if it's referring to a specific field (like prop1 referring to the field prop1).
2. We don't know from within the @properties macro if the user wants to assign the documentation from MyType's field documentation or the property prop1.

Proposed solution

Here's a WIP solution to this.

Inline Documentation

We could do something similar to how DocstringExtensions.jl has FIELDS as an "abbreviation" and take advantage of stored documentation on each type. For example, we can extract field documentation from Dict from base doing:

d = Docs.doc(Dict).meta[:results][1] .  # DocStr type
d.data[:fields] . # where one can store documentation about each field

We could similarly set a :properties key and define stuff inline

@properties MyType begin
  "we have prop1 here"
   prop1(self) => :prop1
  "prop2: add 2 to self"
   prop2(self) -> self + 2
  prop3(self) => :prop1
end

This would theoretically set the :properties in MyType's DocStr.data[:properties] to the corresponding documentation just as any other type could have fields set. Then we could have a similar abbreviation as "FIELDS", maybe "PROPERTIES", for documentation.

This solves the problem of getting documentation in there, but it doesn't really address the problem of automatically binding a fields docs or properties docs to a property.

New Syntax

Maybe something like @fielddoc and @propdoc could be used instead of a docstring inline to trigger a search for the corresponding field or property.

So we could do something like:

@properties MyType begin
    @fielddoc
    prop1(self) => :prop1
   "prop2: add 2 to self"
    prop2(self) -> self + 2
    @propdoc 
   prop3(self) => :prop1
end

This example would produce a dictionary for the properties field in the DocStr instance for MyType as Dict{Any,Any}(:prop1 => "This is field1", :prop2 => "prop2: add 2 to self", :prop3 => "This is property 1")

I'm a lot less certain about this part and don't love it yet.