[haiku-doc] Proposal: Page naming
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Fri, 25 May 2007 12:33:03 +0200
Hi guys,
(this is one of the two issues I wanted to discuss in the last meeting).
I'd like to share some thoughts with you for an amendment to the API
documentation guidelines in regard to the naming of pages, sections,
subsections, etc. etc. etc. Currently, naming pages is a bit of a
random thing. Currently we have fs_modules.dox, usb_modules.dox and
support_intro.dox, and both the MIDI kit's introduction pages. Within
those pages there are sections and subsections which all require an
identifier. Currently those identifiers are a bit random. The thing is
that all the identifiers go into a global namespace, and we are likely
to end up with clashes. So to make all things perfectly clear, I
propose the following naming scheme:
○ The files of \pages should start with an underscore, then the name
of the kit, another underscore and then the name of the page. So, we
would get _support_intro.dox, or _drivers_usb_modules.dox. This kind
of naming will never come into conflict with the documentation for
header files, and because of the leading underscore it will be clear
imediatedly that the file is a page.
○ The page identifier should be the name of the page, without the
underscore. So _drivers_fs_modules.dox will have the '\page
drivers_fs_modules File System Modules' command in it.
○ Sections should start with the page name, and then add the
appropriate section name on. So the introduction of that file should
be '\section drivers_fs_modules_introduction'
○ Any further branches use the same technique: the name of the
parent, an underscore and the name of the subsection.
I think this will make sure we have a clean namespace.
What do you think?
Niels
Other related posts:
