emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: (fn ...) - please fill it at the point of generation


From: Drew Adams
Subject: RE: (fn ...) - please fill it at the point of generation
Date: Sat, 29 Dec 2007 10:14:57 -0800

>    What's the advantage of having one line in a doc string
>    that doesn't fit the doc-string pattern (convention)?
>    How is that more general and less of a special case?
>
> "one line" to munge is more general than "one form".  put
> another way: more tools know how to parse the former than
> the latter.
>
> the "docstring pattern (convention)" is applicable for
> viewing the docstring.  although the part under discussion
> is technically included in the "string", it should be
> semantically distinguished from the rest of the string
> because it is not intended for direct viewing.

Fair enough. If that is the intention, then, yes, it should be not only
semantically but also practically distinguished from the rest of the string
(which is presentation-ready). IOW, we should have separate retrieval
functions for the doc string per se and the interface spec (signature).

> that part is markup, requiring further processing at the
> presentation stage.  to conflate the presentation and the
> generation is a step towards bad design.  a good middle
> path would be to pool common presentation methods, as long
> as those methods are not imposed on the phases uninvolved
> w/ presentation.

The only way currently to recuperate the doc string gives you all of it,
including the part you consider not to be part of the doc string but
"markup".

If that last line (interface spec) is not part of the doc string, and you
want to keep it unfilled because filling is presentation, then
`documentation' (or some other function) should return only the doc string
per se, not the whole kit and caboodle. Especially since `documentation' is
written in C, so it can't be hacked without rebuilding Emacs.

IOW, either the "interface spec" is part of the doc string or it is not. If
it is, then it too should be presentation-ready, like the rest of the
string. If it is not, then we should have a separate function that gives us
only the doc string (without interface spec).






reply via email to

[Prev in Thread] Current Thread [Next in Thread]