Re: [avr-libc-dev] Inclusion of far pointer library (patch #6352)broke avr-libc build

[Joerg Wunsch]

As Jan Waclawek wrote:

> Maybe a bit more narrative than standard documentation, but I wanted
> to spawn a discussion first, I did not expect it will be included
> that soon.

Jan, we all appreciate your effort and contributions, but please, if
you want something discussed, start the discussion *here*.  If you
want to place an additional pointer to the discussion on
avrfreaks.net, that's fine, but this mailing list is the primary
medium to discuss things among those who are interested in further
development of avr-libc.  The list is open to everyone, so any
avrfreaks.net user who is interested can join if they want, and did
not yet -- you might be surprised to see how many people are actually
subscribed to this list, Mailman tells me we've currently got 323
subscribers.  So it's not that nobody would listen here, even if only
one...two dozens out of the subscribers are taking part in
discussions, but that's not different on avrfreaks.net.

Sorry, the article there has the quality of a "HOWTO" document, but
it's nothing I'd consider for inclusion into the documentation (see
below).  I don't have the time to convert it into a documentation
snippet/article right now.

The feature will remain undocumented right now (despite the saying "An
undocumented feature is called a bug"), just so we don't have to back
it out again.  Btw., the segmented memory regions are certainly
nothing to include them into default linker scripts, so if someone
wants to use them, they have to create a custom linker script.  The
documentation for the feature should thus shortly describe how to
create a custom linker script.  .progmem_far might go into the default
linker scripts in a future version I think: it's best if you submitted
a patch to GNU binutils for this, and file it officially into their
bugzilla.  That way, the AVR maintainer(s) of binutils have something
they can refer to within their process.  Sorry there are so many
places to point you at for submitting bug fixes and enhancements, but
we've got three major projects (binutils, GCC, avr-libc), and each of
them has its own process about how patches are being added.  That's
nothing we could change here.

(The following is not just to you, but to everyone contributing.)

When submitting documentation, it would of course always be the best
if you made a stab at creating a Doxygen-style document.  Usually, you
are not required to study the entire Doxygen documentation for this,
but just use the existing avr-libc documentation as a template to get
an idea about how the Doxygen markup works.  (In addition to its own
markup, Doxygen supports all the popular HTML markup tags, so you can
use <tt>, <em> and such.)

However, even without Doxygen tagging, documentation is always
appreciated, and will substantially speedup the integration of
submitted patches.  Our policy says that all features have to be
documented, so a patch adding a new feature but lacking documentation
will frequently not be considered if time is scarce (to the developer
who'd otherwise consider integrating the patch).  Our time budget is
always limited, so if as a developer you have to decide whether to
include an undocumented patch (and create documentation for it), or to
include three documented patches or fix five bugs instead within the
same time, you might guess what the decision is.  (The time ratio is
just an estimation, but is probably not too far off from reality.
Creating documentation costs time, which is often underestimated.
Just in case you're asking yourself next time why your patch,
submitted two years ago, still hasn't been integrated yet...  This
might be the reason.)

There are two basic parts in avr-libc's documentation: the reference
manual, and the user's manual.  (Well, maybe a third one: the FAQ.)
The reference manual is compiled out of the Doxygen comments in all
the header and (C and asm) source files.  Thus, it contains
documentation closely related to the functions, macros and constants
contained in those files.  It can be a bit terse (like the typical
Unix man page), e.g. people are supposed to already know the C
language and how its string concept works, so the main purpose of
documenting strlen() is not to provide an in-depth description about
how C strings are terminated by a '\0' character but to let the users
know avr-libc actually contains a strlen() function.  Description of
the *_PF functions would belong into that category, for example:
developers can reasonably be expected to find the analogy to the
respective standard C functions, so together with a short introduction
to how the far progmem pointers are to be created, that suffices to
know how to make use of these functions.  (The introduction about far
progmem pointers can go into the "blurb" introductional comment on top
of the file avr/pgmspace.h.)

Everything that requires a more detailed description can get an
article of its own in the user's manual.  These files usually end up
in the suffix .dox, living in the directory doc/api.  Technically,
they look like a large C language comment, introduced with /** which
makes Doxygen consider it for parsing.  They get a section name of
their own on top, and this section name also gets a (unique) tag
assigned by the author which can be used to refer from other parts of
the documentation (including the reference manual) by \ref tags.  An
article there would e.g. be appropriate to describe the segmented
progmem access, starting with the conceptional idea and rationale, up
to how to use them, explanation about how to customize a linker script
etc.  Basically, the contents of Jan's explanation in the avrfreaks
thread mentioned looks OK, but it should be in the style of a
technical article, e.g. as if it would be submitted for a periodical
or conference.  Don't talk directly to the user ("You should create a
custom linker script."), but describe it formally ("To use this
feature, a custom linker script must be created.")  While the
reference manual should only have short code examples (so it doesn't
become too big), an article in the user's manual can contain larger
examples as well.

Finally, there's a directory named doc/examples which becomes part of
the manual, too.  Each subdirectory there is expected to contain a
standalone example (including a simple standard Makefile) that is
compilable and runnable provided the user's hardware setup meets the
requirements for it.  Using a popular starter kit like the STK500 or
STK600 is a good idea, but other popular and generally available
hardware will be fine, too (e.g. an Arduino platform would spring to
mind here).  In addition to the C (source and header) files, and maybe
the assembly source code, each directory there gets its own .dox file,
too, which is then used to create the documentation page for the
example project.  To remain in the context of the far pointer library,
an example project would be a good place where a custom linker script
template could be placed into.  A good and comprehensive example could
even obviate the need for an article in the user's manual (but not the
entries for the reference manual).

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)