WIP: cbfs: Add docbook template
PATCH 1/1 WIP: cbfs: Add docbook template
This adds a docbook template for fs, and makes CBFS use it.
Problems (advise please as I have enough 500pp books in my bookshelf):
1. It requires the function names to be repeated. I would like to do this:
/**
* Get the name of a file in CBFS.
*
* @file: The handle to the file.
*
* @return The name of the file, NULL on error.
*/
const char *file_cbfs_name(const struct cbfs_cachenode *file);
but I must do this:
/**
* file_cbfs_name() - Get the name of a file in CBFS. *
* @file: The handle to the file.
*
* @return The name of the file, NULL on error.
*/
const char *file_cbfs_name(const struct cbfs_cachenode *file);
2. It will not accept the doxygen @param style for parameters:
/**
* file_cbfs_name() - Get the name of a file in CBFS. *
* @param file The handle to the file.
*
* @return The name of the file, NULL on error.
*/
const char *file_cbfs_name(const struct cbfs_cachenode *file);
--- doc/DocBook/Makefile | 2 +- include/cbfs.h | 45 +++++++++++++++++++++++---------------------- 2 files changed, 24 insertions(+), 23 deletions(-)
doc/DocBook/Makefile +1 -1
@@ -8,7 +8,7 @@ include $(TOPDIR)/config.mk -DOCBOOKS := linker_lists.xml stdio.xml +DOCBOOKS := fs.xml linker_lists.xml stdio.xml ### # The build process is as follows (targets):
include/cbfs.h +23 -22
122 lines not on this page · raw message
Signature · 1 line
1.7.7.3
PATCH 1/1 WIP: cbfs: Add docbook template
Dear Simon Glass,
Quoted 5 lines
This adds a docbook template for fs, and makes CBFS use it.
Problems (advise please as I have enough 500pp books in my bookshelf):
1. It requires the function names to be repeated. I would like to do this:
Repeating function names is good, you can be sure what the comment is associated with.
[...]
Quoted 1 line
2. It will not accept the doxygen @param style for parameters:
It's not doxygen, sorry. Read [1].
btw. I'd like some kind of @return, but maybe describing the return value in comment is enough.
[...]
[1] http://www.denx.de/wiki/U-Boot/CodingStyle
Best regards,
Marek Vasut
PATCH 1/1 WIP: cbfs: Add docbook template
Hi Marek,
Quoted 11 lines · Marek Vasut
Dear Simon Glass,
Quoted 5 lines
This adds a docbook template for fs, and makes CBFS use it.
Problems (advise please as I have enough 500pp books in my bookshelf):
1. It requires the function names to be repeated. I would like to do this:
Repeating function names is good, you can be sure what the comment is associated with.
Hmmm, well I already know that, since the comment appears immediately above the function...
Quoted 5 lines
[...]
Quoted 1 line
2. It will not accept the doxygen @param style for parameters:
It's not doxygen, sorry. Read [1].
Yes, I was rather hoping there was an easy way to fix these two things. Never mind.
Quoted 3 lines
btw. I'd like some kind of @return, but maybe describing the return value in comment is enough.
Maybe, but it's nice to be explicit. The return value is at least as important as the parameters, and they are called out.
Anyway I will rev the patch with the above in mind.
Regads,
Simon
Quoted 7 lines
[...]
[1] http://www.denx.de/wiki/U-Boot/CodingStyle
Best regards,
Marek Vasut
PATCH 1/1 WIP: cbfs: Add docbook template
Dear Simon Glass,
Quoted 7 lines
Hi Marek,
Quoted 4 lines · Marek Vasut
Dear Simon Glass,
Quoted 2 lines
This adds a docbook template for fs, and makes CBFS use it.
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
Problems (advise please as I have enough 500pp books in my bookshelf):
1. It requires the function names to be repeated. I would like to do this:
Repeating function names is good, you can be sure what the comment is associated with.
Hmmm, well I already know that, since the comment appears immediately above the function...
At the time of writing, yes. But some adjustment of code might mess that up.
Quoted 7 lines
Quoted 4 lines
[...]
Quoted 1 line
2. It will not accept the doxygen @param style for parameters:
It's not doxygen, sorry. Read [1].
Yes, I was rather hoping there was an easy way to fix these two things. Never mind.
I'd say there is, but let's fix it in Linux kernel too. Actually, I have a pile of patches for Linux kernel's documentation, but it's hard to get any documentation patches in :-C
Quoted 5 lines
Quoted 2 lines
btw. I'd like some kind of @return, but maybe describing the return value in comment is enough.
Maybe, but it's nice to be explicit. The return value is at least as important as the parameters, and they are called out.
I agree (!).
Quoted 1 line
Anyway I will rev the patch with the above in mind.
[...]
btw. It'd be nice to be able to patch the upstream (linux's) kerneldoc :-(
Best regards,
Marek Vasut