[editor-hints-devel] My thoughts about markup and docstrings

[Luis Oliveira]

Robert Goldman <rpgoldman at sift.info> writes:

> As someone who uses ELI more than SLIME, still, I would prefer to see a
> technique that extended the existing documentation facility, rather than
> supplanting it and dictating a particular development environment.  I
> even work with people who use vim, and there are also Cusp, and Allegro
> and LispWorks' IDEs.

If I understand the overall design correctly, you have a couple of
options:

   1. implement a module for your favorite IDE. It seems to me that this
      approach has got plenty of potential since the IDE can employ
      pretty markup and make proper use of any metadata that the
      ANNOTATE-DOCUMENTATION macro might provide.

   2. if it's not possible or convenient to implement such a module, then
      one could inspect the annotations, strip the markup and
      (setf documentation) as you suggested.


> [...]
> That said, where would such configuration options live?  Would they be
> attached to an ASDF system (hard to see off hand how this would work),

It seems to me that this sort of thing is a global user preference and
should not be dictated by the system/package.


> I suspect all of these remarks are symptoms of an underlying discomfort
> with the concept.  I'm uncomfortable with the idea of having
> documentation that is compiled separately, in some kind of batch mode,
> rather than being compiled incrementally together with the code.

This problem doesn't apply to option (1). To cater to option (2),
perhaps the ANNOTATE-DOCUMENTATION macro could delegate its work when
the PARSE-DOCSTRINGS system is pre-loaded? A beefier function in that
system could then take care of checking user preferences and whatnot,
and proceed with option (2) if appropriate.

-- 
Luís Oliveira
http://student.dei.uc.pt/~lmoliv/