Display "Remarks" section above the classes list when documenting namespaces

Jul 28, 2013 at 5:44 PM
Edited Jul 28, 2013 at 5:52 PM
Hi there,

I would like to ask if there is any way to include the "remarks" section of a namespace documentation page above the namespace's contents. Please let me explain what I am trying to achieve with an example.

Please take a look at:
http://msdn.microsoft.com/en-us/library/system.componentmodel.aspx

In that page, we can see the following excerpt:

 
The System.ComponentModel namespace provides classes that are used to implement the run-time and design-time behavior of components and controls. This namespace includes the base classes and interfaces for implementing attributes and type converters, binding to data sources, and licensing components.
 

Then it has an additional section, right below, that I am guessing would be the "remarks" section of the documentation (probably it isn't, but I couldn't find a proper name for that - it does not seems to belong to the summary section as it is outside the "<div class="summary">" in the page's HTML source). Only then it provides the list of code elements belonging to this namespace.

Now, in SHFB v1.8.7.0, if I generate documentation for a namespace using the NamespaceDoc method, the "Remarks" section will be below the element listings. Is there any option to include text between the summary and the namespace contents?

An example of the current behavior is available on
http://accord-net.github.io/docs/html/N_Accord_Math.htm

If that is not currently possible, I would be happy to open an issue at the issue tracker in case this could be someday implemented in the future.

Best regards,
Cesar
Coordinator
Jul 28, 2013 at 7:21 PM
Bear in mind that Microsoft's MSDN layout bears to resemblance to anything currently in Sandcastle and I don't recall any info being given on how they handle namespace comments. They don't handle code comments the same as we do since they are managed independently of the code. At a guess, it's possible they extract the first paragraph and tag it as the summary and render any remaining paragraphs after it in a separate div. The presentation styles in Sandcastle don't do that.

You could just merge the remarks into new paragraphs in the summary namespace comments. It's possible you could conditionally render the remarks after the summary when it's a namespace topic and suppress the normal remarks section in a similar manner. Stuff like that is best implemented using a custom presentation style which you can create on your own. See the Custom Presentation Style Definition File and its related walkthrough for more information.

Eric
Jul 28, 2013 at 7:50 PM
Thanks Eric,

I am doing some experimentation here to see what works best. My first thought was also to include everything in the summary section as you mentioned, but I was afraid the the entire summary contents would be listed in the project's Index page, where all namespaces are listed at once (with their summaries on the right). I am just waiting for the documentation to finish compiling to check what happens.

Best regards,
Cesar
Jul 28, 2013 at 9:12 PM
Yeah, as I suspected, unfortunately adding everything to the "summary" section, even if using distinct paragraphs, causes the whole section to be displayed at the Index page in the documentation...

I will take a look about creating a custom presentation style definition, thanks for pointing that out. But if you ever feel it would be a useful feature to have, like perhaps a feature to display only the first paragraph from the summary section at the namespace listings, I would definitely vote for it being included someday :-P

Thanks again for the help!

Best regards,
Cesar
Jun 26, 2014 at 12:59 PM
Yes i need that too :-)
Jun 27, 2014 at 6:38 AM
cesarsouza wrote:
I will take a look about creating a custom presentation style definition, thanks for pointing that out. But if you ever feel it would be a useful feature to have, like perhaps a feature to display only the first paragraph from the summary section at the namespace listings, I would definitely vote for it being included someday :-P

Thanks again for the help!

Best regards,
Cesar
Di you succes to do that ? I have not a lost of time to try to understand how template are working...