CEDET

Ahh.. documentation for tags.  What a great example of how
semantic abstracts out behaviors.

semantic-documentation-for-tag is a overloaded function created with
`define-overload'.  It has a default behavior which either returns the
:documentation attribute, or just grabs any comment preceding the
give tag, and returns the body of that comment.

For any language with a special way of storing the documentation for a
given tag, you can write a new implementation just for that language.
If you want to grab some text from HTML, you could do that.  If you
have an Emacs Lisp function you can query Emacs for the doc.

If you would like this feature to work with python you can either
teach the parser to put in :documentation attributes (which can make
TAG files really huge,) or you can write a bit of lisp to find the doc
inside the tag.

See bovine/semantic-el.el for how to override this function to make it
work right for some other language.  eg:

(define-mode-local-override semantic-documentation-for-tag
  emacs-lisp-mode (tag &optional nosnarf)
  "Return the documentation string for TAG.
Optional argument NOSNARF is ignored."
  (let ((d (semantic-tag-docstring tag)))
    (when (not d)
      (cond ((semantic-tag-buffer tag)
	     ;; Doc isn't in the tag itself.  Lets pull it out of the
	     ;; sources.
	     (let ((semantic-elisp-store-documentation-in-tag t))
	     ....

Adding this to python would be a great new feature.

Also, your function is similar to semantic-ia-show-doc.  If you end up
with an improvement it would be spiff to replace the short tool I
have.

Thanks
Eric

>>> joakim@... seems to think that:
>I'm having some trouble making (semantic-documentation-for-tag) return
>something useful.
>
>I have code llike this:
>
>(defun jv-finddoc-main (point)
>  "Display the code-level documentation for the symbol at POINT."
>  (interactive "d");"P"
>  
>  (save-excursion 
>    (with-output-to-temp-buffer "*TAG DOCUMENTATION*"
>      (let* ((ctxt (semantic-analyze-current-context point))
>             (cursym (semantic-ctxt-current-symbol))
>             (thing (semantic-ctxt-current-thing ))
>             (pf (reverse (oref ctxt prefix)))
>             (tag (car pf))
>             (symbol-buffer-mode major-mode)
>             )
>        ;; If PF, the prefix is non-nil, then the last element is either
>        ;; a string (incomplete type), or a semantic TAG.  If it is a TAG
>        ;; then we should be able to find DOC for it.
>
>        (set-buffer "*TAG DOCUMENTATION*")        ;;figure out stuff about the buffer where the symbol lives, before this call
>
>        (cond ((stringp tag)
>               (princ "Incomplete symbol name."))
>              ((semantic-tag-p tag)
>               
>               (let ((doc 
>                      (condition-case err
>                          (semantic-documentation-for-tag  tag)  ;; look at tag for docs, or before tag for comments
>                        ;;feels dodgy, seems it looks at point instead of tag
>                        ;; maybe not. saves excursion, and jumps to tag
>
>                        (error  (format  "oops semantic-documentation-for-tag crashed %s " err)))
>                          )
>...
>
>The provlem is  (semantic-documentation-for-tag  tag) rarely returns
>anything useful except maybe a comment preceeding the tag.
>
>If I do M-x  (semantic-documentation-for-tag) on a lisp function I
>might get the proper documentation for that function sometimes, but
>not for a python definition like:
>
>def mupp(r):
>   """lalala"""
>   return r
>
>In the end what I want to achieve is:
>- show snarfed documentation if there is one for symbol at point
>- do language specific documentation lookup for at least python, java
>and ocaml
>

-- 
          Eric Ludlam:                 zappo@..., eric@...
   Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org

"Eric M. Ludlam" <eric@...> writes:

> If you would like this feature to work with python you can either
> teach the parser to put in :documentation attributes (which can make
> TAG files really huge,) or you can write a bit of lisp to find the doc
> inside the tag.

Thanks for this info. I'll have a look at implementing a Python doc
grabber the later way.

> See bovine/semantic-el.el for how to override this function to make it
> work right for some other language.  eg:
>
> (define-mode-local-override semantic-documentation-for-tag
>   emacs-lisp-mode (tag &optional nosnarf)
>   "Return the documentation string for TAG.
> Optional argument NOSNARF is ignored."
>   (let ((d (semantic-tag-docstring tag)))
>     (when (not d)
>       (cond ((semantic-tag-buffer tag)
> 	     ;; Doc isn't in the tag itself.  Lets pull it out of the
> 	     ;; sources.
> 	     (let ((semantic-elisp-store-documentation-in-tag t))
> 	     ....
>
> Adding this to python would be a great new feature.
>
> Also, your function is similar to semantic-ia-show-doc.  If you end up
> with an improvement it would be spiff to replace the short tool I
> have.

The code was originally snarfed from ia-show-doc.

Also, I figured out why my modified code didnt work.

I had a (set-buffer "*TAG DOCUMENTATION*") call before
(semantic-documentation-for-tag  tag) which aparently confused it.
Intuitively it shouldnt.

(I have the (set-buffer ...) call so I can do         (insert-button
"jump to definition" 'action 'jv-finddoc-button-jump 'tag-to-jump-to
tag) later )


>           Eric Ludlam:                 zappo@..., eric@...
>    Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
> Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org

-- 
Joakim Verona
http://www.verona.se

>>> joakim@... seems to think that:
>"Eric M. Ludlam" <eric@...> writes:
  [ ... ]
>>
>> Adding this to python would be a great new feature.
>>
>> Also, your function is similar to semantic-ia-show-doc.  If you end up
>> with an improvement it would be spiff to replace the short tool I
>> have.
>
>The code was originally snarfed from ia-show-doc.
>
>Also, I figured out why my modified code didnt work.
>
>I had a (set-buffer "*TAG DOCUMENTATION*") call before
>(semantic-documentation-for-tag  tag) which aparently confused it.
>Intuitively it shouldnt.
>
>(I have the (set-buffer ...) call so I can do         (insert-button
>"jump to definition" 'action 'jv-finddoc-button-jump 'tag-to-jump-to
>tag) later )
  [ ... ]

The default has this in it:

  (:override
   ;; No override.  Try something simple to find documentation nearby
   (save-excursion
     (set-buffer (semantic-tag-buffer tag))
     (semantic-go-to-tag tag)
     (or

so it should be immune to you switching buffers.  Perhaps you are
querying tags that do not have buffer info for some reason?

Eric

-- 
          Eric Ludlam:                 zappo@..., eric@...
   Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org

"Eric M. Ludlam" <eric@...> writes:

>>>> joakim@... seems to think that:
>>"Eric M. Ludlam" <eric@...> writes:
>   [ ... ]
>>>
>>> Adding this to python would be a great new feature.

Already this simple thing somewhat works:

(define-mode-local-override semantic-documentation-for-tag
  python-mode (&optional tag nosnarf)
  "return python def doc string:

def mupp(r):
\"\"\" lalala \"\"\"
   return r

"
  (when (or tag (setq tag (semantic-current-tag)))
    (with-current-buffer (semantic-tag-buffer tag)
      (save-excursion
        ;; Move the point at token start
        (goto-char (semantic-tag-start tag))
        (forward-line) ; pyhon doc comment starts below the def
        (let* ((p1 (point))
               (dummy (forward-sexp))
               (p2 (point)) ;p1 and p2 now supposedly surround the comment
               )
          (buffer-substring p1 p2))))))


It must be made a little bit more clever though:

- make sure we are really looking at a string """ or "
- move forward over """ or "
- do forward-sexp
- skip back over """ or "
- return the string...

Im surely forgetting some complexity here, but I was pleasently
surprised by this simplicity.

More complex will be how to handle system documentation for library
symbols. Do you have any hints there?



>>> Also, your function is similar to semantic-ia-show-doc.  If you end up
>>> with an improvement it would be spiff to replace the short tool I
>>> have.
>>
>>The code was originally snarfed from ia-show-doc.
>>
>>Also, I figured out why my modified code didnt work.
>>
>>I had a (set-buffer "*TAG DOCUMENTATION*") call before
>>(semantic-documentation-for-tag  tag) which aparently confused it.
>>Intuitively it shouldnt.
>>
>>(I have the (set-buffer ...) call so I can do         (insert-button
>>"jump to definition" 'action 'jv-finddoc-button-jump 'tag-to-jump-to
>>tag) later )
>   [ ... ]
>
> The default has this in it:
>
>   (:override
>    ;; No override.  Try something simple to find documentation nearby
>    (save-excursion
>      (set-buffer (semantic-tag-buffer tag))
>      (semantic-go-to-tag tag)
>      (or
>
> so it should be immune to you switching buffers.  Perhaps you are
> querying tags that do not have buffer info for some reason?

I will look into this.

>
> Eric
>
> -- 
>           Eric Ludlam:                 zappo@..., eric@...
>    Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
> Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org

-- 
Joakim Verona
http://www.verona.se

>>> joakim@... seems to think that:
>"Eric M. Ludlam" <eric@...> writes:
>
>>>>> joakim@... seems to think that:
>>>"Eric M. Ludlam" <eric@...> writes:
>>   [ ... ]
>>>>
>>>> Adding this to python would be a great new feature.
>
>Already this simple thing somewhat works:
>
>(define-mode-local-override semantic-documentation-for-tag
>  python-mode (&optional tag nosnarf)
>  "return python def doc string:
>
>def mupp(r):
>\"\"\" lalala \"\"\"
>   return r
>
>"
>  (when (or tag (setq tag (semantic-current-tag)))
>    (with-current-buffer (semantic-tag-buffer tag)
>      (save-excursion
>        ;; Move the point at token start
>        (goto-char (semantic-tag-start tag))
>        (forward-line) ; pyhon doc comment starts below the def
>        (let* ((p1 (point))
>               (dummy (forward-sexp))
>               (p2 (point)) ;p1 and p2 now supposedly surround the comment
>               )
>          (buffer-substring p1 p2))))))
>
>
>It must be made a little bit more clever though:
>
>- make sure we are really looking at a string """ or "
>- move forward over """ or "
>- do forward-sexp
>- skip back over """ or "
>- return the string...
>
>Im surely forgetting some complexity here, but I was pleasently
>surprised by this simplicity.

One trick is to use the semantic lexer.  Just ask it to parse starting
at point and if the python lexer is set up right, it will give you a
string.  I don't remember much of the details.  I seem to remember
this being the right thing to do.

>More complex will be how to handle system documentation for library
>symbols. Do you have any hints there?

Do you mean you need to parse the libraries to extract the doc, or is
there a processor that has done that already, like doxygen?

Eric

-- 
          Eric Ludlam:                 zappo@..., eric@...
   Home: http://www.ludlam.net            Siege: http://www.siege-engine.com
Emacs: http://cedet.sourceforge.net               GNU: http://www.gnu.org