Bug 491451

Summary:	Add syntax details for opaque structures
Product:	Red Hat Directory Server	Reporter:	Deon Ballard <dlackey>
Component:	Doc-plugin-programming-guide	Assignee:	Marc Muehlfeld <mmuehlfe>
Status:	CLOSED WONTFIX	QA Contact:	Viktor Ashirov <vashirov>
Severity:	medium	Docs Contact:
Priority:	high
Version:	8.1	CC:	jgalipea, nhosoi, nkinder, wibrown
Target Milestone:	---	Keywords:	Documentation
Target Release:	---
Hardware:	All
OS:	Linux
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2017-02-09 00:14:37 UTC	Type:	---
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:
Bug Depends On:
Bug Blocks:	512820

Description Deon Ballard 2009-03-21 05:04:47 UTC

According to Nathan's comments for the Slapi_Counter edits in bug 458190, the new write-up for Slapi_Counter includes the private definition. The public header (slapi-plugin.h) doesn't have any of this detail in it. For example:

#include "slapi-plugin.h" 
typedef struct Slapi_Counter {
    PRUint64 value;
#ifndef ATOMIC_64BIT_OPERATIONS
    Slapi_Mutex *mutex;
#endif
} Slapi_Counter;

We should add something similar to the Syntax sections for other opaque structures, such as the Slapi_PBlock.

Comment 1 Deon Ballard 2009-09-02 14:22:33 UTC

Changing the status from "new" to "assigned."

Comment 3 Deon Ballard 2009-09-22 17:36:44 UTC

Setting to block the DS9 docs tracking bug.

Comment 9 Deon Ballard 2014-07-10 16:49:03 UTC

Reassigning to Tomas.

Comment 10 Noriko Hosoi 2017-02-09 00:14:37 UTC

It is not worth showing all the fields in the slapi structures.

Plus, there are some reasons we'd better not to do so.
1) The fields are not meant to access directly. Only the API info to access them should be provided.
2) The fields could be updated frequently by debugging or implementing new features.  Having a snapshot of the structure syntax should be rather harmful.

Hence, closing this bug with WONTFIX. (Acked by Nathan.  Thanks!!)

Comment 11 wibrown@redhat.com 2017-02-09 00:52:00 UTC

Another part of this, is that in the future, I'm going to hide and mask these. You should never access struct internals, only the functions related to them.