Closed Bug 912360 Opened 11 years ago Closed 4 months ago

[patch] NSS documentation

Categories

(NSS :: Documentation, enhancement, P5)

enhancement

Tracking

(Not tracked)

RESOLVED INACTIVE

People

(Reporter: mbartos, Unassigned)

References

Details

Attachments

(1 file)

90.09 KB, patch
mbartos
: review?
rrelyea
briansmith
: feedback+
ryan.sleevi
: feedback-
Details | Diff | Splinter Review
I've added doxygen documentation into NSS sources (patch attached, logo is at http://mbartos.fedorapeople.org/doxygen3/html/logo.png, I can't find option to append more attachements). There is currently no documentation and functions are not split into public/private modules. This needs to be done by NSS developers who know what that particular functions are for. There is a little README for that at http://mbartos.fedorapeople.org/README.doxygen. This patch is supposed to serve as a first step towards useful NSS documentation.

I'd like to read you opinion, ideas how to improve it etc.

Thanks,
Milan Bartos

P.S.: I've been told to ask wtc and Bob Relyea for review. I can't find Bob in that Requestee text field, so only wtc is there. Sorry
Attachment #799301 - Flags: review?(wtc)
Keywords: checkin-needed
Please don't request checkin on a patch that hasn't gotten r+ yet.
Keywords: checkin-needed
Comment on attachment 799301 [details] [diff] [review]
nss_add_doxygen.patch

Bob, could you review this patch? Thanks.
Attachment #799301 - Flags: review?(wtc) → review?(rrelyea)
Comment on attachment 799301 [details] [diff] [review]
nss_add_doxygen.patch

Review of attachment 799301 [details] [diff] [review]:
-----------------------------------------------------------------

yes, I can review it wtc. I asked Milan to request you or ryan just to make sure someone outside red hat sees the patch. What we really want is your feedback on whether you may have issues with the idea of the patch. Thanks,

bob
Attachment #799301 - Flags: feedback?(wtc)
Comment on attachment 799301 [details] [diff] [review]
nss_add_doxygen.patch

Ryan, Brian: please take a look at this proposal to use doxygen in NSS
source files.

Bob: I am fine with using doxygen if it is fine with you.

Hi Milan,

I read your sample at http://mbartos.fedorapeople.org/README.doxygen.
The comments for functions look fine and remind me of javadoc.
The "/**<" comment delimiter for structure fields and enumerators looks
a little annoying. Can that be customized?

The \addtogroup command also looks a little annoying, but I think
it's not used that often (ideally at most twice per header file).
Attachment #799301 - Flags: feedback?(wtc)
Attachment #799301 - Flags: feedback?(ryan.sleevi)
Attachment #799301 - Flags: feedback?(brian)
Comment on attachment 799301 [details] [diff] [review]
nss_add_doxygen.patch

Review of attachment 799301 [details] [diff] [review]:
-----------------------------------------------------------------

I took a quick look at this patch. It seems good. But I am not familiar with doxygen.
Thanks for creating this patch.

::: doc/Makefile
@@ +16,4 @@
>  name = nss-man
>  date = `date +"%Y%m%d"`
>  
> +all: prepare all-man all-html build_doxygen

Nit: we should standardize on using '-' or '_'. Existing NSS
makefiles use '_' more often.

@@ +83,5 @@
> +
> +#--------------------------------------------------------
> +# doxygen documentation
> +#--------------------------------------------------------
> +DOXYGEN_DIR = ./doxygen

Is it necessary to use "./"? I don't think things like vpath or VPATH
applies to $(DOXYGEN_DIR).

::: doc/doxygen/DoxygenLayout.xml
@@ +11,5 @@
> +    </tab>
> +    <tab type="user" visible="yes" url="globals_func.html" title="Functions"/>
> +    <tab type="classes" visible="yes" title="">
> +      <tab type="classlist" visible="yes" title="" intro=""/>
> +      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 

This doesn't really matter, but the code review tool highlights two spaces
at the end of lines in this file.
Attachment #799301 - Flags: feedback+
Comment on attachment 799301 [details] [diff] [review]
nss_add_doxygen.patch

Review of attachment 799301 [details] [diff] [review]:
-----------------------------------------------------------------

I'm never sure the right flags to set, so I'm setting f-, even though I do think this is fine/good/f+ etc

My one nit is on the advice of http://mbartos.fedorapeople.org/README.doxygen in putting function documentation into the .c files.

I think it's much more useful/appropriate that they be in the header files, *not* the implementation files, on the basis that:
1) On developer machines, they should be able to look purely at the NSS headers to determine the appropriate interface
2) We should be coding against interfaces, not implementation details. If a side-effect is not documented, it's arguably a bug - OR it's an undocumented behaviour that SHOULD NOT be relied upon.

My experience with Doxygen documentation is that, while it's helpful for some degree of class diagrams, I invariably find myself resorting back to the header files to actually find how things are supposed to behave (or, in the case of NSS, the implementations as well). I'd much prefer the headers be the canonical source of the behaviour, rather than requiring a separate lookup in (the implementation, the doxygen files)

::: doc/doxygen/DoxygenLayout.xml
@@ +4,5 @@
> +  <navindex>
> +    <tab type="mainpage" visible="yes" title=""/>
> +    <tab type="pages" visible="yes" title="" intro=""/>
> +    <tab type="modules" visible="yes" title="" intro=""/>
> +    <tab type="namespaces" visible="yes" title="">

NSS, being C, won't ever have namespaces - at least in the C++ sense.

Seems like it can be dropped from the nav bar.

The same arguably applies to classes (Line 13), but ISTR that Doxygen treats structs as classes (the former we WOULD want enumerated), so it may be fine
Attachment #799301 - Flags: feedback?(ryan.sleevi) → feedback-
(In reply to Ryan Sleevi from comment #8)
> I'm never sure the right flags to set, so I'm setting f-, even though I do
> think this is fine/good/f+ etc
> 
> My one nit is on the advice of
> http://mbartos.fedorapeople.org/README.doxygen in putting function
> documentation into the .c files.
> 
> I think it's much more useful/appropriate that they be in the header files,
> *not* the implementation files, on the basis that:
> 1) On developer machines, they should be able to look purely at the NSS
> headers to determine the appropriate interface
> 2) We should be coding against interfaces, not implementation details. If a
> side-effect is not documented, it's arguably a bug - OR it's an undocumented
> behaviour that SHOULD NOT be relied upon.

Yes, I strongly agree with rsleevi that the API documentation should be in the header files.

I am fine with using doxygen as long as:

1. It is possible to automatically verify that the doxygen stuff is correct by running the doxygen build command and looking at the result on all tier 1 platforms (Windows, Mac, and Linux). This means that there must be clear and relatively easy-to-follow instructions for getting the doxygen tools and whatever installed on all platforms.

OR:

2. We agree that it is OK to break the doxygen stuff with the expectation that somebody will fix it later.

In other words, we cannot require developers to keep the doxygen documentation generation working if it is difficult/impossible for them to test it on their platform of choice. (Note that I primarily use Windows.)
Attachment #799301 - Flags: feedback?(brian) → feedback+
Thank you ryan, brian and wtc for your feedback.

bob
Severity: normal → S3
Severity: S3 → N/A
Status: UNCONFIRMED → RESOLVED
Type: defect → enhancement
Closed: 4 months ago
Priority: -- → P5
Resolution: --- → INACTIVE
You need to log in before you can comment on or make changes to this bug.