This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 151365 - Layer file documentation
Summary: Layer file documentation
Status: RESOLVED DUPLICATE of bug 149136
Alias: None
Product: platform
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 6.x
Hardware: All All
: P3 blocker (vote)
Assignee: Jesse Glick
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2008-10-25 14:04 UTC by puce
Modified: 2008-12-22 10:41 UTC (History)
1 user (show)

See Also:
Issue Type: ENHANCEMENT
Exception Reporter:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description puce 2008-10-25 14:04:31 UTC
There should be a documentation about the layer file and all it's possible attributes.

Suggestion: Provide a mechanism to allow modules to sepcify their extension points. Something like XSDs, but maybe more
specific (and also XML based), which doesn't allow to specify new elements but allows to specify:
- the extension point folder (absolute path)
- the supported file attributes (including their types (see XSD)/ enumeration of supported values (see XSD)) 
- allow to specify alternative sets of attributes and allow to specify, which attributes are mandatory and which optional
- allow to annotate all these definitions with documention (see XSDs)

Pay attention to reuse XSD-mechansims as much as possible (eg. the type-definitions etc.).

Dynamically create an XSD from all these definition files of the current module and all its dependent modules.

These files could then be used to generate a documentation of the extension points of a module.

The dynamically created XSD can be used to validate the layer file and to provide code completion.

Create these files for all extension points in all modules of the openide.
Comment 1 Jesse Glick 2008-10-25 19:43:55 UTC
Seems you missed

http://wiki.netbeans.org/DeclarativeRegistrationUsingAnnotations

*** This issue has been marked as a duplicate of 149136 ***
Comment 2 tomwheeler 2008-10-27 03:35:08 UTC
Isn't the point about the documentation (ignoring the request for enhancement about how layer files could be improved)
still valid?  

I don't know of any comprehensive documentation on the contents of the System Filesystem.  All I was able to find was
the DTD and a incomplete set of module-by-module examples in the Javadoc.  I asked on the dev@openide list and no one
else could point me to anything more.  So while I agree that the annotation-based approach described in #149136 negates
to some extent RFEs for layer files, it does not address documenting what could possibly go into a layer file.

Based on your preference, I will either reopen this issue or open a new one regarding system filesystem documentation.
Comment 3 Jesse Glick 2008-10-27 19:04:22 UTC
If annotations are available for SPIs you might like to use (and clearly displayed in the regular Javadoc for that
module), then there is no need for an existential list of possible SFS entries. What would you use it for?

Regarding the existing index of SFS entries in Javadoc - if you find particular items that are missing, please file a
defect for the corresponding module, as every module's arch.xml is supposed to enumerate these things. A general issue
complaining that the list is incomplete will have no particular owner and will likely be ignored.