Add documentation per snippet

[victorteokw]

Add documentation region to snippet template, maybe like this:

# -*- mode: snippet; require-final-newline: nil -*-
# name: assert_operator
# key: assert_operator
# --
assert_operator(${1:o1}, ${2:op}, ${3:o2 = UNDEFINED}, ${4:msg = nil})$0
# -- documentation
For testing with binary operators.
  assert_operator 5, :<=, 4

Then user may see documentation when using auto-complete together with yasnippet.

[stardiviner]

Seems great, I always hope auto-complete popup can show the snippet content in popup doc. Maybe this can be implemented too.

[npostavs]

The proposed syntax wouldn't allow # -- to appear in the body of the snippet.

[victorteokw]

How about

# -*- mode: snippet; require-final-newline: nil -*-
# name: assert_operator
# key: assert_operator
# documentation: 
For testing with binary operators.
  assert_operator 5, :<=, 4
# --
assert_operator(${1:o1}, ${2:op}, ${3:o2 = UNDEFINED}, ${4:msg = nil})$0

[stardiviner]

Looks great.

[npostavs]

How about [...]

I think that can work. Next question is how other packages will access this value?

[stardiviner]

company-mode can access meta info and document easily. Yasnippet need to create an api for other packages.

[npostavs]

Yasnippet need to create an api for other packages.

Right, my question was how should this api look like?

[stardiviner]

yas--get-document(snippet &optional short-document?) , Like this? short-document means return short document or not. Like one line snippet description. People might set "snippet key" different with "snippet name". So return "snippet name" as short description in completion framrwork's "meta" (like company-mode).

[npostavs]

yas--get-document(snippet &optional short-document?) , Like this?

I was going to ask how should an external package get a hold of snippet without knowing about yasnippet's internals in the first place, but taking a quick look at https://github.com/company-mode/company-mode/blob/master/company-yasnippet.el I see it's already going deep into the internals of yasnippet, so I guess that's we'll have to worry about later.

[glepnir]

see this pr https://github.com/company-mode/company-mode/pull/965