~ubuntu-branches/ubuntu/trusty/monodevelop/trusty-proposed

el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (String.Format (" Badly formed XML in at comment file `{0}': cannot be included ", file)), el);

195

Report.Warning (1592, 1, mc.Location, "Badly formed XML in included comments file -- `{0}'", file);

196

}

197

}

198

if (doc != null) {

199

try {

200

XmlNodeList nl = doc.SelectNodes (path);

201

if (nl.Count == 0) {

202

el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" No matching elements were found for the include tag embedded here. "), el);

203

204

keep_include_node = true;

205

}

206

foreach (XmlNode n in nl)

207

el.ParentNode.InsertBefore (el.OwnerDocument.ImportNode (n, true), el);

208

} catch (Exception ex) {

209

el.ParentNode.InsertBefore (el.OwnerDocument.CreateComment (" Failed to insert some or all of included XML "), el);

210

Report.Warning (1589, 1, mc.Location, "Unable to include XML fragment `{0}' of file `{1}' ({2})", path, file, ex.Message);

211

}

212

}

213

}

214

return keep_include_node;

215

}

216

217

218

// Handles <see> elements.

219

220

void HandleSee (MemberCore mc, TypeContainer ds, XmlElement see)

221

{

222

HandleXrefCommon (mc, ds, see);

223

}

224

225

226

// Handles <seealso> elements.

227

228

void HandleSeeAlso (MemberCore mc, TypeContainer ds, XmlElement seealso)

229

{

230

HandleXrefCommon (mc, ds, seealso);

231

}

232

233

234

// Handles <exception> elements.

235

236

void HandleException (MemberCore mc, TypeContainer ds, XmlElement seealso)

237

{

238

HandleXrefCommon (mc, ds, seealso);

239

}

240

241

242

// Handles <typeparam /> node

243

244

static void HandleTypeParam (MemberCore mc, XmlElement node)

245

{

246

if (!node.HasAttribute ("name"))

247

return;

248

249

string tp_name = node.GetAttribute ("name");

250

if (mc.CurrentTypeParameters != null) {

251

if (mc.CurrentTypeParameters.Find (tp_name) != null)

252

return;

253

}

254

255

// TODO: CS1710, CS1712

256

257

mc.Compiler.Report.Warning (1711, 2, mc.Location,

258

"XML comment on `{0}' has a typeparam name `{1}' but there is no type parameter by that name",

259

mc.GetSignatureForError (), tp_name);

260

}

261

262

263

// Handles <typeparamref /> node

264

265

static void HandleTypeParamRef (MemberCore mc, XmlElement node)

266

{

267

if (!node.HasAttribute ("name"))

268

return;

269

270

string tp_name = node.GetAttribute ("name");

271

var member = mc;

272

do {

273

if (member.CurrentTypeParameters != null) {

274

if (member.CurrentTypeParameters.Find (tp_name) != null)

275

return;

276

}

277

278

member = member.Parent;

279

} while (member != null);

280

281

mc.Compiler.Report.Warning (1735, 2, mc.Location,

282

"XML comment on `{0}' has a typeparamref name `{1}' that could not be resolved",

283

mc.GetSignatureForError (), tp_name);

284

}

285

286

FullNamedExpression ResolveMemberName (IMemberContext context, MemberName mn)

287

{

288

if (mn.Left == null)

289

return context.LookupNamespaceOrType (mn.Name, mn.Arity, LookupMode.Probing, Location.Null);

290

291

var left = ResolveMemberName (context, mn.Left);

292

var ns = left as Namespace;

293

if (ns != null)

294

return ns.LookupTypeOrNamespace (context, mn.Name, mn.Arity, LookupMode.Probing, Location.Null);

295

296

TypeExpr texpr = left as TypeExpr;

297

if (texpr != null) {

298

var found = MemberCache.FindNestedType (texpr.Type, ParsedName.Name, ParsedName.Arity);

299

if (found != null)

300

return new TypeExpression (found, Location.Null);

301

302

return null;

303

}

304

305

return left;

306

}

307

308

309

// Processes "see" or "seealso" elements from cref attribute.

310

311

void HandleXrefCommon (MemberCore mc, TypeContainer ds, XmlElement xref)

312

{

313

string cref = xref.GetAttribute ("cref");

314

// when, XmlReader, "if (cref == null)"

315

if (!xref.HasAttribute ("cref"))

316

return;

317

318

// Nothing to be resolved the reference is marked explicitly

319

if (cref.Length > 2 && cref [1] == ':')

320

return;

321

322

// Additional symbols for < and > are allowed for easier XML typing

323

cref = cref.Replace ('{', '<').Replace ('}', '>');

324

325

var encoding = module.Compiler.Settings.Encoding;

326

var s = new MemoryStream (encoding.GetBytes (cref));

327

SeekableStreamReader seekable = new SeekableStreamReader (s, encoding);

328

329

var source_file = new CompilationSourceFile (doc_module);

330

var report = new Report (doc_module.Compiler, new NullReportPrinter ());

331

332

var parser = new CSharpParser (seekable, source_file, report);

333

ParsedParameters = null;

334

ParsedName = null;

335

ParsedBuiltinType = null;

336

ParsedOperator = null;

337

parser.Lexer.putback_char = Tokenizer.DocumentationXref;

338

parser.Lexer.parsing_generic_declaration_doc = true;

339

parser.parse ();

340

if (report.Errors > 0) {

341

Report.Warning (1584, 1, mc.Location, "XML comment on `{0}' has syntactically incorrect cref attribute `{1}'",

342

mc.GetSignatureForError (), cref);

343

344

xref.SetAttribute ("cref", "!:" + cref);

345

return;

346

}

347

348

MemberSpec member;

349

string prefix = null;

350

FullNamedExpression fne = null;

351

352

353

// Try built-in type first because we are using ParsedName as identifier of

354

// member names on built-in types

355

356

if (ParsedBuiltinType != null && (ParsedParameters == null || ParsedName != null)) {

357

member = ParsedBuiltinType.Type;

358

} else {

359

member = null;

360

}

361

362

if (ParsedName != null || ParsedOperator.HasValue) {

363

TypeSpec type = null;

364

string member_name = null;

365

366

if (member == null) {

367

if (ParsedOperator.HasValue) {

368

type = mc.CurrentType;

369

} else if (ParsedName.Left != null) {

370

fne = ResolveMemberName (mc, ParsedName.Left);

371

if (fne != null) {

372

var ns = fne as Namespace;

373

if (ns != null) {

374

fne = ns.LookupTypeOrNamespace (mc, ParsedName.Name, ParsedName.Arity, LookupMode.Probing, Location.Null);

375

if (fne != null) {

376

member = fne.Type;

377

}

378

} else {

379

type = fne.Type;

380

}

381

}

382

} else {

383

fne = ResolveMemberName (mc, ParsedName);

384

if (fne == null) {

385

type = mc.CurrentType;

386

} else if (ParsedParameters == null) {

387

member = fne.Type;

388

} else if (fne.Type.MemberDefinition == mc.CurrentType.MemberDefinition) {

389

member_name = Constructor.ConstructorName;

390

type = fne.Type;

391

}

392

}

393

} else {

394

type = (TypeSpec) member;

395

member = null;

396

}

397

398

if (ParsedParameters != null) {

399

var old_printer = mc.Module.Compiler.Report.SetPrinter (new NullReportPrinter ());

400

try {

401

var context = new DocumentationMemberContext (mc, ParsedName ?? MemberName.Null);

402

403

foreach (var pp in ParsedParameters) {

404

pp.Resolve (context);

405

}

406

} finally {

407

mc.Module.Compiler.Report.SetPrinter (old_printer);

408

}

409

}

410

411

if (type != null) {

412

if (member_name == null)

413

member_name = ParsedOperator.HasValue ?

414

Operator.GetMetadataName (ParsedOperator.Value) : ParsedName.Name;

415

416

int parsed_param_count;

417

if (ParsedOperator == Operator.OpType.Explicit || ParsedOperator == Operator.OpType.Implicit) {

418

parsed_param_count = ParsedParameters.Count - 1;

419

} else if (ParsedParameters != null) {

420

parsed_param_count = ParsedParameters.Count;

421

} else {

422

parsed_param_count = 0;

423

}

424

425

int parameters_match = -1;

426

do {

427

var members = MemberCache.FindMembers (type, member_name, true);

428

if (members != null) {

429

foreach (var m in members) {

430

if (ParsedName != null && m.Arity != ParsedName.Arity)

431

continue;

432

433

if (ParsedParameters != null) {

434

IParametersMember pm = m as IParametersMember;

435

if (pm == null)

436

continue;

437

438

if (m.Kind == MemberKind.Operator && !ParsedOperator.HasValue)

439

continue;

440

441

var pm_params = pm.Parameters;

442

443

int i;

444

for (i = 0; i < parsed_param_count; ++i) {

445

var pparam = ParsedParameters[i];

446

447

if (i >= pm_params.Count || pparam == null || pparam.TypeSpec == null ||

448

!TypeSpecComparer.Override.IsEqual (pparam.TypeSpec, pm_params.Types[i]) ||

449

(pparam.Modifier & Parameter.Modifier.RefOutMask) != (pm_params.FixedParameters[i].ModFlags & Parameter.Modifier.RefOutMask)) {

450

451

if (i > parameters_match) {

452

parameters_match = i;

453

}

454

455

i = -1;

456

break;

457

}

458

}

459

460

if (i < 0)

461

continue;

462

463

if (ParsedOperator == Operator.OpType.Explicit || ParsedOperator == Operator.OpType.Implicit) {

464

if (pm.MemberType != ParsedParameters[parsed_param_count].TypeSpec) {

465

parameters_match = parsed_param_count + 1;

466

continue;

467

}

468

} else {

469

if (parsed_param_count != pm_params.Count)

470

continue;

471

}

472

}

473

474

if (member != null) {

475

Report.Warning (419, 3, mc.Location,

476

"Ambiguous reference in cref attribute `{0}'. Assuming `{1}' but other overloads including `{2}' have also matched",

477

cref, member.GetSignatureForError (), m.GetSignatureForError ());

478

479

break;

480

}

481

482

member = m;

483

}

484

}

485

486

// Continue with parent type for nested types

487

if (member == null) {

488

type = type.DeclaringType;

489

} else {

490

type = null;

491

}

492

} while (type != null);

493

494

if (member == null && parameters_match >= 0) {

495

for (int i = parameters_match; i < parsed_param_count; ++i) {

496

Report.Warning (1580, 1, mc.Location, "Invalid type for parameter `{0}' in XML comment cref attribute `{1}'",

497

(i + 1).ToString (), cref);

498

}

499

500

if (parameters_match == parsed_param_count + 1) {

501

Report.Warning (1581, 1, mc.Location, "Invalid return type in XML comment cref attribute `{0}'", cref);

502

}

503

}

504

}

505

}

506

507

if (member == null) {

508

Report.Warning (1574, 1, mc.Location, "XML comment on `{0}' has cref attribute `{1}' that could not be resolved",

509

mc.GetSignatureForError (), cref);

510

cref = "!:" + cref;

511

} else if (member == InternalType.Namespace) {

512

cref = "N:" + fne.GetSignatureForError ();

513

} else {

514

prefix = GetMemberDocHead (member);

515

cref = prefix + member.GetSignatureForDocumentation ();

516

}

517

518

xref.SetAttribute ("cref", cref);

519

}

520

521

522

// Get a prefix from member type for XML documentation (used

523

// to formalize cref target name).

524

525

static string GetMemberDocHead (MemberSpec type)

526

{

527

if (type is FieldSpec)

528

return "F:";

529

if (type is MethodSpec)

530

return "M:";

531

if (type is EventSpec)

532

return "E:";

533

if (type is PropertySpec)

534

return "P:";

535

if (type is TypeSpec)

536

return "T:";

537

538

throw new NotImplementedException (type.GetType ().ToString ());

539

}

540

541

542

// Raised (and passed an XmlElement that contains the comment)

543

// when GenerateDocComment is writing documentation expectedly.

544

545

// FIXME: with a few effort, it could be done with XmlReader,

546

// that means removal of DOM use.

547

548

void CheckParametersComments (MemberCore member, IParametersMember paramMember, XmlElement el)

549

{

550

HashSet<string> found_tags = null;

551

foreach (XmlElement pelem in el.SelectNodes ("param")) {

552

string xname = pelem.GetAttribute ("name");

553

if (xname.Length == 0)

554

continue; // really? but MS looks doing so

555

556

if (found_tags == null) {

557

found_tags = new HashSet<string> ();

558

}

559

560

if (xname != "" && paramMember.Parameters.GetParameterIndexByName (xname) < 0) {

561

Report.Warning (1572, 2, member.Location,

562

"XML comment on `{0}' has a param tag for `{1}', but there is no parameter by that name",

563

member.GetSignatureForError (), xname);

564

continue;

565

}

566

567

if (found_tags.Contains (xname)) {

568

Report.Warning (1571, 2, member.Location,

569

"XML comment on `{0}' has a duplicate param tag for `{1}'",

570

member.GetSignatureForError (), xname);

571

continue;

572

}

573

574

found_tags.Add (xname);

575

}

576

577

if (found_tags != null) {

578

foreach (Parameter p in paramMember.Parameters.FixedParameters) {

579

if (!found_tags.Contains (p.Name) && !(p is ArglistParameter))

580

Report.Warning (1573, 4, member.Location,

581

"Parameter `{0}' has no matching param tag in the XML comment for `{1}'",

582

p.Name, member.GetSignatureForError ());

583

}

584

}

585

}

586

587

588

// Outputs XML documentation comment from tokenized comments.

589

590

public bool OutputDocComment (string asmfilename, string xmlFileName)

591

{

592

XmlTextWriter w = null;

593

try {

594

w = new XmlTextWriter (xmlFileName, null);

595

w.Indentation = 4;

596

w.Formatting = Formatting.Indented;

597

w.WriteStartDocument ();

598

w.WriteStartElement ("doc");

599

w.WriteStartElement ("assembly");

600

w.WriteStartElement ("name");

601

w.WriteString (Path.GetFileNameWithoutExtension (asmfilename));

602

w.WriteEndElement (); // name

603

w.WriteEndElement (); // assembly

604

w.WriteStartElement ("members");

605

XmlCommentOutput = w;

606

module.GenerateDocComment (this);

607

w.WriteFullEndElement (); // members

608

w.WriteEndElement ();

609

w.WriteWhitespace (Environment.NewLine);

610

w.WriteEndDocument ();

611

return true;

612

} catch (Exception ex) {

613

Report.Error (1569, "Error generating XML documentation file `{0}' (`{1}')", xmlFileName, ex.Message);

614

return false;

615

} finally {

616

if (w != null)

617

w.Close ();

618

}

619

}

620

}

621

622

623

// Type lookup of documentation references uses context of type where

624

// the reference is used but type parameters from cref value

625

626

sealed class DocumentationMemberContext : IMemberContext

627

{

628

readonly MemberCore host;

629

MemberName contextName;

630

631

public DocumentationMemberContext (MemberCore host, MemberName contextName)

632

{

633

this.host = host;

634

this.contextName = contextName;

635

}

636

637

public TypeSpec CurrentType {

638

get {

639

return host.CurrentType;

640

}

641

}

642

643

public TypeParameters CurrentTypeParameters {

644

get {

645

return contextName.TypeParameters;

646

}

647

}

648

649

public MemberCore CurrentMemberDefinition {

650

get {

651

return host.CurrentMemberDefinition;

652

}

653

}

654

655

public bool IsObsolete {

656

get {

657

return false;

658

}

659

}

660

661

public bool IsUnsafe {

662

get {

663

return host.IsStatic;

664

}

665

}

666

667

public bool IsStatic {

668

get {

669

return host.IsStatic;

670

}

671

}

672

673

public ModuleContainer Module {

674

get {

675

return host.Module;

676

}

677

}

678

679

public string GetSignatureForError ()

680

{

681

return host.GetSignatureForError ();

682

}

683

684

public ExtensionMethodCandidates LookupExtensionMethod (TypeSpec extensionType, string name, int arity)

685

{

686

return null;

687

}

688

689

public FullNamedExpression LookupNamespaceOrType (string name, int arity, LookupMode mode, Location loc)

690

{

691

if (arity == 0) {

692

var tp = CurrentTypeParameters;

693

if (tp != null) {

694

for (int i = 0; i < tp.Count; ++i) {

695

var t = tp[i];

696

if (t.Name == name) {

697

t.Type.DeclaredPosition = i;

698

return new TypeParameterExpr (t, loc);

699

}

700

}

701

}

702

}

703

704

return host.Parent.LookupNamespaceOrType (name, arity, mode, loc);

705

}

706

707

public FullNamedExpression LookupNamespaceAlias (string name)

708

{

709

throw new NotImplementedException ();

710

}

711

}

712

713

class DocumentationParameter

714

{

715

public readonly Parameter.Modifier Modifier;

716

public FullNamedExpression Type;

717

TypeSpec type;

718

719

public DocumentationParameter (Parameter.Modifier modifier, FullNamedExpression type)

720

: this (type)

721

{

722

this.Modifier = modifier;

723

}

724

725

public DocumentationParameter (FullNamedExpression type)

726

{

727

this.Type = type;

728

}

729

730

public TypeSpec TypeSpec {

731

get {

732

return type;

733

}

734

}

735

736

public void Resolve (IMemberContext context)

737

{

738

type = Type.ResolveAsType (context);

739

}

740

}

741

}

Older »