Re: docstrings and elisp reference

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > It’s worth mentioning that JavaDoc documentation style is particularly
  > useful for Object-Oriented Programming and strongly typed languages.  I
  > think it’s even mandatory with OOP to be readable.

I could be mistaken, but I think that Javadoc is comparable to Emacs
Lisp doc strings.

If that is correct, then of course Javadoc documentation is useful.
Emacs Lisp doc strings are useful too.  But concatenating them does
not make a clear tutorial/reference manual.  We need both!

  > However, I also think Jean-Christophe makes a good point about
  > documentation generation.  Not with duplication, but semantic support.

What is "semantic support"?

  > Those tools are highly effective for semantic indexation for newcomers

What is that?

  > since they offer a simple interface for hundred FLOSS libraries.

Could you explain what "a simple interface" to a library means?
Normally each library defines its own interface.

                                                                      GNU
  > projects are almost nonexistent.

You can't mean that literally, so what do you mean?

Maybe "semantic support" should be added to Emacs Lisp,
but until I know what it means, I can't have an opinion.

  > I’ve been trying in the past to port GNU projects documentation and I
  > finally gave up.  I find Texinfo to be very limited when it comes to
  > semantic support.  It’s really hard to extract meaningful definitions
  > from texi files.

I think what you are trying to do does not make sense.  You can't
extract the full description of a single function from a good manual
because a good manual does not try to describe each function
separately.  What you want for this is something like a doc string,
and a good manual is not like a collection of doc strings.


-- 
Dr Richard Stallman
President, Free Software Foundation (gnu.org, fsf.org)
Internet Hall-of-Famer (internethalloffame.org)
Skype: No way! See stallman.org/skype.html.