This is the mail archive of the
mailing list for the GCC project.
Re: [RFC] Documenting support functions and data structures
- From: Manuel López-Ibáñez <lopezibanez at gmail dot com>
- To: Andrew Haley <aph at redhat dot com>
- Cc: Mikhail Maltsev <maltsevm at gmail dot com>, gcc Mailing List <gcc at gcc dot gnu dot org>
- Date: Thu, 16 Apr 2015 18:16:47 +0200
- Subject: Re: [RFC] Documenting support functions and data structures
- Authentication-results: sourceware.org; auth=none
- References: <552F44B1 dot 3090001 at gmail dot com> <552F6CF7 dot 1020401 at redhat dot com> <552FB77C dot 40200 at gmail dot com> <552FD22A dot 7090203 at redhat dot com>
On 16 April 2015 at 17:15, Andrew Haley <firstname.lastname@example.org> wrote:
> However, I am advising caution, particularly when documenting
> structures whose shape might soon change. And with respect to new
> contributions, it would be a shame if someone came along, did a great
> job of documenting the structures and interfaces, then left after a
> while, leaving the docs to rot.
That is life, and it can happen to a newcomer or a long-time
contributor. If there is interest, it will be maintained, if not they
will rot until the point that it is better to delete them. At least we
can easily delete rotten docs, not so easy with code.
Having something like this in gccint or in the wiki can motivate
someone to, for example, finally get rid of obsolete data structures
that are rarely used. It could also be a starting point to continue
this: https://gcc.gnu.org/wiki/ModularGCC by categorizing files in
terms of their purpose and putting them together. Also to identify
things in liberty that GCC does not actually use (thus no need
documenting them) and things that are duplicated with gnulib (we
should just use the gnulib version). Even if the only benefit of the
list was to make easier for Mikhail to continue contributing to GCC,
it would be a net win.
Of course, if someone knows that a particular structure is going to
change soon, then please tell Mikhail to not bother documenting in
detail that one in particular just yet.